Best practices for creating documentation collectively
Looking for guidelines, theory and best practices for creating documentation collectively
- think about who is the audience?
- how much participation are you seeking?
- how much ownership is necessary to sustain it?
- think about version control
- think about maintenance
- think about documentation for the documentation:
- Documentation for how to navigate the documentation
- Documentation for how to contribute to the documentation
- communities
- keeping track of who is contributing, asking them to look at new documentation
- avoid gate-keeping
- lots of technical options/tools
- Github , markdown , popular but here is a technical barrier
- Read the docs, with hypothesis plugin to add comments
- Myst (?) https://myst-parser.readthedocs.io/en/latest/
- Google docs , easy to use, security issues, heavy and slow
- MediaWiki (e.g. Wikipedia) can be self-hosted
- wiki.js, dokuwiki, xwiki
- MKDocs, here's what the CiviCRM community is using - https://docs.civicrm.org/dev/en/latest/documentation/ (in early days we used Floss manuals - https://flossmanuals.net/)
- Github , markdown , popular but here is a technical barrier
- Localization and translation
- can't be an afterthought
- translation platforms
- weblate (FOSS)
- bit heavy software-development focus
- weblate (FOSS)
- proprietary:
- transifex
- Crowdin
Difficulties
- lack of capacity
- volunteer contributions are of varying quality
Typology of Documentation:
- "The Grand Unified Theory of Documentation" https://documentation.divio.com
- Tutorials | How-to's | Explanation | Reference
- Video tutorial: https://www.youtube.com/watch?v=tXWscUSYdBs&t=818s
- Tutorials | How-to's | Explanation | Reference
Another typology:
- https://www.smartics.eu/confluence/display/PDAC/Documentation+Quadrants
- Project docs (charter, etc) | Process docs (minutes, etc) | Product docs (for users) | System docs (tech specs)
mailing list focused on discussing network-centric resources/documentation:
Readme driven development, documentation driven development
Preserving institutional memory can be encouraged by documentation
When to start documentation? In what part of development cycle
Freshness dates tied to documentation
some (technical-oriented) documentation systems:
- https://readthedocs.org/
- https://docusaurus.io/
- https://www.sphinx-doc.org/en/master/
- https://www.mkdocs.org/
- https://www.gitbook.com/
- (others please add to this list)
free JS-based search for open-source and nonprofits:
Well documented documentation, guiding people to where and how to use and improve the documentation
This was the system that I saw being used that automatically applies badges to contributors etc based on lots of metrics -- it's crappy software, don't use it, just get a trial and steal its ideas :)
- https://www.zoho.com/desk/knowledge-base-software.html
- https://www.zoho.com/desk/multibrand-help-center.html
How do we avoid knowledge gate-keeping or strategies to engage or move towards collective ownership?