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

Table 10: Better documentation - collaborative authorship


#1

Goals:

  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
#2

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.”


#3

Thanks so much for great documentation of the documentation discussion!


#4

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!