A community of technology community managers, leaders, and builders.

Table 10: Better documentation - collaborative authorship



  1. better documentation / good editing vs good content
  2. feedback on documentation
  3. making documentation a priority
  4. collaborative documentation (recruiting collaborators)
  5. governance
  6. accessible documentation (across audiences, esp from tech to non tech)

** DOCS OR IT DIDN’T HAPPEN! ** (h/t Write the Docs)

ITEM 1: Better documentation / Good editing vs good content

  • don’t just document the trees, must document the forest
  • lead with storytelling, follow with reference (makes maintenance easier)
  • differentiate user guides (knowledge base) from overview/reference docs
  • allow draft docs from devs, use tech writer for final draft
  • got legacy but still used docs? disclaim as historical, don’t delete

ITEM 2: Feedback on documentation

  • tools: Docbook, Atlas, ReadTheDocs.org (yay Write the Docs), Asciidoctor, “documentation continuous integration services”
  • feedback on reference style docs in style of bug reporting, feedback on knowledge base docs in style of open commenting/discussion
  • cautionary tales
  • (not much interaction between readers)
  • (mis-filed bug reports, solved w/ red bug icon linking to bug report form w/ smart defaults)

ITEM 3: Making docs a priority

  • start from day zero
  • needs a champion, keep other projects from getting in the way - a dedicated doc worker
  • must be as important as code, can’t be a second class citizens
  • file bug reports when docs are lacking!
  • make a part of code review process
  • “impact” flag for public facing code, so impacted code w/o docs automatically creates bug report
  • author docs NOW rather than later, make a part of the process, automate as much doc generation possible, put into unit tests
  • monthly doc day
  • pair programming / documenting

ITEM 4: Collaborative documentation (recruiting collaborators)

  • allow beginners / newcomers to write - must have a place to put new content
  • source answers / painpoints from forums, bug trackers, etc
  • source content from the rest of the internet (eg, bloggers)
  • find common questions and search queries in forums, IRC, etc

ITEM 5: Governance

  • community / collaborative review
  • ? Open Data - launched with list of topics, solicited volunteers per topic to flesh it out for X months, then solicit volunteers for technical and copy editing (ack requirement)
  • ? Open Stack - defined need, use core group (in a room together!) in book sprint, send out open call (even if raw)
  • ? Open Advice & Producing Open Source Software

ITEM 6: Accessible documentation
CHALLENGE: developers for users, even technical users (or academics for non-academics, etc)

  • monitor search terms, forums, knowledge base (also monitor paths)

  • cautionary tale: external searches are not necessarily representative - ~60-80% are now encrypted/HTTPS

  • add “synonyms” to docs

  • if your docs are meant to be read in a linear fashion, make sure users entering from external sites have context

  • explain path through the forest, not just description of trees

  • share w/ outsiders

  • prose/overviews can be littered with links into nitty gritty

  • docs don’t need to reflect code structure necessarily, users don’t see system the same way its developers do

Community Documentation

To encourage everyone to check out these neat books, here are links!

Open Advice: “Open Advice is a knowledge collection from a wide variety of Free Software projects. It answers the question what 42 prominent contributors would have liked to know when they started so you can get a head-start no matter how and where you contribute.”

Producing Open Source Software: “Producing Open Source Software is a book about the human side of open source development. It describes how successful projects operate, the expectations of users and developers, and the culture of free software.”


Thanks so much for great documentation of the documentation discussion!


You’re very welcome! I figured I never documented my code well, so I had better get this one right :wink:

Thanks to for being the kind sponsor for this forum!