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/)
• Localization and translation
  • can't be an afterthought
  • translation platforms
    • weblate (FOSS)
      • bit heavy software-development focus
  • 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

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:

• https://www.fabriders.net/network-centric/

Readme driven development, documentation driven development

• https://tom.preston-werner.com/2010/08/23/readme-driven-development.html

Preserving institutional memory can be encouraged by documentation When to start documentation? In wwhatpart 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:

• https://www.algolia.com/for-open-source/

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?