[WIP] FAIR Documentation system #185
Description
This issue will serve as the primary tracking issue for defining a comprehensive documentation system for the FAIR project. The needs might change in the future, but here we will try to minimise this possibility, as moving documentation to a different tool and changing workflows can be very slow and painful (as we saw in the WordPress project). Therefore, I cannot stress enough the importance of discussing and walking through every possible documentation aspect BEFORE we start building any infrastructure.
In this issue, we want to discuss the tools and workflows for working on documentation. Also, we need to define all the documentation types we plan to work on.
Types of documentation
- For project consumers (knowledge base)
- site owners and maintainers (FAIR Connect)
- package (plugin, theme, translation) authors (FAIR Forge)
- hosting providers
- agencies, developers
- etc.
- For project maintainers (contributing docs)
- ONBOARDING (for every aspect of contribution) - I'd say this is the highest priority
- contributing with code (FAIR Connect, FAIR Forge, infrastructure)
- contributing with documentation (all)
- contributing to management roles
- contributing with translations (for the platform and/or packages)
- etc.
Every type of documentation can come in different forms.
- Theoretical knowledge:
- Reference (information-oriented)
- Explanation (understanding-oriented)
- Practical steps:
- Tutorials (learning-oriented)
- How-to guides (problem-oriented)
Tools
We are not looking just for the tools for writing and hosting documentation, we are considering other extremely important parameters, such as governance, contribution, tracking contributions, translations, accessibility, findability, extensibility, tool's maturity, implementations, etc. @courtneyr-dev did a search across other open-source platforms, evaluating and scoring different tools and workflows (see fairpm-docs-platform-research.pdf).
As expected, there is no single tool that can handle all our requirements, so it's natural to split them into larger groups. The first larger groups can be:
- tools for writing the documentation
- tools for hosting the documentation
- tools for automating connections between these two
For every tool we choose, we want it to be:
- accessible,
- translatable,
- open-source
- reliable and mature project
And we want a clear plan for continuing without it.
Tools for writing the documentation
Who is going to write documentation, and what are their needs?
Criteria for writing tool:
- easy (enough) for onboarding
- easy (enough) for writing
- easy for reviewing
- easy for triaging and maintaining
- easy for translating content
- auto-tracking contributions
- version control
- can handle documentation for multiple versions of software (complex taxonomy system)
- can handle different media types (videos, images, GIFs, etc.)
- advanced notifications system for various events (e.g. a paragraph has been updated, all translation contributors for that article/page are being notified about this change, etc.)
Tools for hosting the documentation
Criteria for hosting tool:
- logical discoverability
- advanced search function (can handle complex search with multiple filters)
- can handle multi-lingual content
- easy reporting issues (on the spot, two clicks)
- can handle multiple colour schemes (so we can adjust for different accessibility profiles)
Tools for automating syncing between writing and hosting tools
Criteria for automation tool:
- sync between writing and hosting tool as soon as possible
- easy to set up
- easy to maintain
- possibility for extending?
Supply chain
People involved in documentation are not just consumers and creators. It's a complete chain, and smart projects can convert it to a supply chain.
The chain:
- Consumer - uses the docs and occasionally notices errors
- Reporter - consumer reports errors they find (assuming it's very clear how to do it from the place where they found the error)
- One-time contributor (these can be multiple-time contributors, but as long as they don't actively come to contribute, they are considered as one-time contributors) - some reporters will fix small issues (given it's very clear and easy to do so from the place where they found the error)
- Potential contributor - one-time contributors might seek a way to help out the project outside of their occasional fixes (given there is a proper Getting started and ONBOARDING documentation). Mentoring programs can really help, especially at the beginning, when onboarding documentation hasn't been created yet. This is the time to write it.
- Active contributor - actively working on issues
- Maintainer - managing issues and active contributors
Requirements and needs for every persona in a chain
Workflows
Mentorship
One of the most important workflows in sustainable open-source projects is mentorship. I'm not talking about a traditional mentorship format with a mentor and a mentee. Because we are all adults with specific sets of skills, knowledge, and experience, we can learn from each other, so we can be mentors and mentees at the same time. It's just a matter of pairing people.
There can be a number of different types of pairs; one type, developer and documentor, is already explained in this comment. Others can be in the lead on the release, deploying the release, onboarding new developers or other contributors, triaging issues, etc. The point of pairing people isn't just about learning/teaching someone something new.
It's about constant sharing of collective knowledge, so that the project never faces the bus factor of 1.
Contributing with code
Every developer knows how different code development workflows can be, especially when working with different teams. Therefore, an open-source project can not assume what's "best practice" and expect new contributors to be familiar with it. The best practice is what we define as best for the project. And it is important to note every step. As I couldn't find those general "best practice" steps documented in any repository, I'll propose one here.