- See previous Docs Chat Summary (January 10)
- In attendance: @JavierCasares @dcavins @im4th @emaralive
- Slack archive
PS: we were so captivated to learn from @JavierCasares (one of the WP Hosting Team reps & the Lead for the WordPress Advanced Administration Handbook) on using GitHub to contribute to an open source project’s documentation that we completely dedicated this chat on this subject.
Let’s learn from the Hosting and the Advanced Administration Handbooks
GitHub main benefits:
- A place where documentation can be edited by “anyone”.
- A place where we can track documentation tasks (or issues) & discuss out loud and visualize progress using Projects.
- A way to standardize how to write documentation using the Markdown language.
- A transparent contributing / publishing workflow.
- Documentation’s repository content is regularly synchronized (every 15 mins) with a WordPress site thanks to the Handbook plugin.
- A place where we can keep track about Documentation’s history.
NB: the manifest.json is the main controller for the synchronization task. As long as a documentation page is not referenced into it, it’s not synchronized.
Dealing with “Markdown’s fear”:
A concern we discussed a while back was about the fact Markdown / Github can limit contributions when it comes to writing User documentation: some people willing to contribute might consider “learning” Markdown or using GitHub a discouraging step. @JavierCasares told us the Spanish Community Handbook (es) is using the GitHub “bridge” and shared with us how they dealt with this:
- Explaining what is GitHub (es).
- Explaining what is Markdown and how to use it (es).
Important things to keep in mind for BP Docs
- Documentation is as important as code.
- Try to keep the handbook structure easy: limit folders tree to 2 levels.
- Having an Advanced user section might be needed.
- Work on a best path to quickly start enjoying BuddyPress (“documentation wizard”).
- Choosing the GitHub “bridge” way was the right move and we’ll be ready for a very interesting future about reading documentation in many languages (@JavierCasares told us about the GlotPress project about parsing Markdown to ease Documentation translations.
Next Docs-Chat
It will happen on February 7, 2024 at 19:00 UTC (that’s tomorrow, agenda will follow shortly!) in #BuddyPress.
📖 👩🏽🤝👨🏻
BP Team Updates 