• In attendance: @jasonrouet @dcavins @im4th
• Slack archive

Quick note: I was largely afk in August, I was on summer holiday + sick for a week and when I went back to work I had a lot on my plate. I’ll do my best to publish the summaries as quickly as possible from now on. 💪

FYI: here’s the agenda we published before the meeting.

As the agenda was quite long, we didn’t have time to discuss all the items, so we have covered the main issues. Here’s the recap of the BP Docs-Chat on Slack:

1. Discussion about how to host @imath tutorial published on the previous BP Docs-Chat summary + extra discussion about the future documentation structure 

Props from @jasonrouet about @imath work, it’s fantastic and it will help new contributors (and even existing ones) dive into the new documentation on Github.

As for now, the tutorial only have been published on the bpdevel.wordpress.com website. It has to be available on the Github repo directly with further information about how to contribute to the BuddyPress project globally and to documentation specifically.

To do so, we discussed the /docs subdirectory and the needs to improve the folder structure. On the BP repo, we already have a /docs/ subdirectory where all the documentation will be added. Then we’ll have to polish the structure like this:

• – /docs/user/ with all resources on how end-users can use BP
• – /docs/dev/ with all technical resources for devs to learn how BP works
• – /docs/contributor/ with all resources on how to contribute to the BP project

We discussed the /doc/contributor/ structure and said it could be organised like this:

• /docs/contributor/
• /docs/contributor/code/ with resources on how to contribute to BP codebase
• /docs/contributor/documentation/ with resources on how to contribute to BP documentation
• /docs/contributor/translation/ with resources on how to translate BP

@imath said he’ll move the tutorial to /docs/contributor/documentation and improve it with the latest screenshots he made.

To improve the tutorial, @bouncingsprout suggested starting a visual presentation (maybe a flowchart?) of the steps involved in the process to help people understand how to contribute. We all agree it could be useful to people who aren’t used to Github.

2. What to keep from the existing Documentation structure/content? Where to start building the new documentation?

@jasonrouet started the discussion by suggesting importing the contents of the existing documentation (the codex), then sorting out what is no longer up to date, what needs to be updated and what can be kept as it is still up-to-date. The aim would be to start from the existing content, rearrange it and then add new content.

@imath and @dcavins said the actual documentation is very outdated, screenshots need to be updated and shouldn’t be imported as is.

@im4th shared a PDF file listing all the existing content from the codex:

Rather than importing the actual content from the codex as is. It was suggested to think about the structure and what kind of content will be added to the documentation and then pick interesting information from the codex after checking it is still accurate.

@im4th said the team tried to update the codex at the beginning of the year but gave up as it was very deprecated and is suggesting starting from scratch rather than loosing too much time and energy starting from the existing content. Here’s a link to the result of the previous attempt to update the codex for the record.

At this point in the discussion, it seemed clear that the codex is kind of frozen and to be kept as an archive for users of previous versions of BP.

Moreover, let’s keep in mind that the release notes are also part of the documentation. We’ll have to rediscuss how to link the release notes with the rest of the documentation (e.g how release notes can help identify what part of the documentation needs updates).

So here’s our initial process idea:

• have a look at the codex structure as an example to build the structure of the new documentation but we won’t rely on it at all for the content,
• based on the PDF file, tag the content: “very outdated” for content that will not be imported, “need update” for content that could be imported after edition and “up to date” for content that can be added as is,
• once done, contributors will be able to assign themselves the content to update, create, import and start PRs.

How to document BuddyPress efficiently in a structured way is something we’ll learn and adapt over time.

Other lower-priority topics discussed.

• @jasonrouet has been invited as a contributor to the official Github BP repo by @imath with permission to sort the future PRs related to the documentation. Also a project (kanban view) has been started on the github repo to help sort the future PRs. We’ll have to think about the workflow to help sort the PRs.
• How to coordinate with the core team about the next release (12.0.0): how to track changes, additions, deletions… @im4th suggested he will write a summary of the changes, specifically Rewrites API will change lots of things for users and devs.
• If the codex is frozen (excepting the release notes section), wouldn’t it be a good idea to display a warning explaining that new documentation is in progress with a link to Github and a clear message about the codex being frozen/mostly outdated? @imath said he’ll ping @johnjamesjacoby to see how to put something like that on the codex.

#docs-chat, #summary