Best practices for creating documentation collectively

From DevSummit
Jump to navigation Jump to search

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


  • lack of capacity
  • volunteer contributions are of varying quality

Typology of Documentation:

Another typology:

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:

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 :)

How do we avoid knowledge gate-keeping or strategies to engage or move towards collective ownership?