Here’s the recap of the BP Docs-Chat on Slack:
1. Follow-up on the actions planned for August
- Starting a discussion with @johnjamesjacoby on how to add a warning message on the codex
-> See last docs-chat summary for more details.
@im4th said he’ll reach out to JJJ about this item (nothing urgent).
- Deploying the tutorial on how to contribute to the new doc directly on Github
@im4th committed it to trunk here: https://github.com/buddypress/buddypress/tree/master/docs/contributor/documentation
As we said during the previous meeting, this PR is kind of a tutorial on its own, as it initiates subdirectories and shows what content might look like on Github.
- Quick news: how are things going for 12.0.0?
@im4th said beta testers are still needed. 12.0.0-beta2 will probably be packaged on September 7.
For now, the documentation team isn’t ready to manage release notes on the new documentation. But it’s an opportunity to think about how we’ll document everything a release adds/removes/changes in the future.
The 12.0.0 release should help us identify the process to be implemented for the documentation team to update the content once the release notes are generated.
@vapvarun shared with us how release notes are generated. When 10.0 and 11.0 were released, the following plugin, built by @rayisme was used to generate release notes: https://github.com/r-a-y/bp-changelog
@im4th and @bouncingsprout quickly said it would be great to improve it to handle markdown formatting and maybe add some github action.
2. Main item of our meeting: how to start working on the content over the next two weeks:
The plan discussed is:
- @im4th will share a csv file listing all the existing content urls from the codev to @jasonrouet who’ll create a spreadsheet on GDrive for the team to work on it easily,
- once the spreadsheet shared with the team, people will be able to:
- review: we’ll need @im4th and @dcavins help specifically to comment each urls by saying if:
- the content is up-to-date (maybe it needs more details, but could be imported as is to the new doc)
- the content needs editing (some parts of the content change but it’s still a relevant piece of content)
- the content is totally outdated and should be rewritten from scratch (some pages could still be needs, others not anymore if it refers to some feature that doesn’t exist at all)
- edit: once a url has been reviewed by someone with enough experience, it will be ready for assignment. Someone will then be able to take charge of editing the content (see tutorial on how to contribute to the doc for the steps).
- Alongside, the work on the importing the content from the codex. We’ll have to reconsider how the content is structured. At first we’ll probably start with something close to the current codex structure and then progressively reorganise things based on the updated content.
So basically, the “reviewers” (a.k.a our gatekeepers as @bouncingsprout named them 😀 ) will add some kind of ‘inline comment’ on the spreadsheet. It will help “editors” know what to remove/amend/rewrite.
The initial work on sorting/importing content from the codex once done, we’ll be able to say “we are done with the codex, everything still up to date on the old documentation is already in the new documentation” and focus on producing new content that doesn’t exist on the codex (edited)
Starting by sorting/editing and importing the articles of the codex, we will quickly be able to ensure that what is still up-to-date in the codex is also already available in the new documentation (with updated screenshots, references to the latest versions, etc.). Then we’ll be able to focus on producing new content for the new documentation without having to care about the codex at all (with one exception: the release notes will still be published via the codex for now).
3. Language quality check: how can we ensure that the documentation is written in proper English? Is en-US the default language localisation?
Intro: it’s best to adopt good habits from the start. A significant part of the team won’t be English natives.
The group agreed on having en-US as the default language. Quick note from @jasonrouet: remember to set your tools like Deepl/Grammarly/LanguageTools/… to that specific locale! 😉
We said, language check (spelling/punctuation/grammar) should be part of the quality checks at the same level as Markdown formatting check, technical content check…
For now, Ben and David agreed to check the language. We’ll document this process in /master/docs/contributor/documentation/.
4. Get inspiration from what the WordPress project documentation team is doing
@bouncingsprout said he’ll introduce himself and attend some meetings from that team to collect good practices. Ben said they have a good new contributor onboarding process, internal team processes, etc… All good for the team, any external advice is welcome, we need our own processes, but learning from the team that has been working for years and that has already carried out a migration from their old codex to a new documentation is certainly worthwhile.
Finally, he said he’ll be our cookie dealer, copying @milanacap strategy! 🍪 See you at a WordCamp to share a snack together! 😉
Next Docs-Chat
It will happen on September 20 at 19:00 UTC in #BuddyPress. We are a small but friendly team, everyone is welcome to contribute: this may be done by editing the documentation or by sending us feedback on what is missing from the documentation.
#docs-chat, #summary
BP Team Updates 