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

Documentation to build communities


3:30pm session

Notes by Ian Tien and Andy Oram


  • Michael: neo4j, ASCII doctor, documentation in one place, live documentation generated from tests. Wants to hear new ideas
  • Georg: Bosch InnerSource, used to write documentation by self, but couldn’t maintain, still figuring out a good way to write documentation
  • Taylor: developer evangualist for Keen.io. Documentation is good, but could be better. Mixed with API reference, and documentation is in its own repo. Have tutorials and guides, then users write blog posts as well.
  • Jackson: community events from New Relic, looking for business process documentation.
  • Nate Willis: tech journalist, many projects don’t have enough documentation, makes it difficult to develop.
  • David: Ubuntu community team, manage developer portal, Ubuntu technologies are transitioning, API references, SDK, guides and tutorials, need to transition to new model
  • Daniel: Ubuntu, how to make APIs, SDKs, all materials digestable for app developers
  • Ilan: Data Dog, community team includes docs, interested in general
  • Jeremy: from LinuxQuestions.org
  • Tony: moving inner source codes to GitBook, going to mandate all checks it to have test
  • Don Day (later), founder of DITA

Documentation tools

  • ASCII docs (better than markdown because it has macros, other features needed for docs)
  • GitBook (moving there from FrameMaker)
  • Sphinx

Darwin Information Type Architecture (DITA), community on XML format for docs, community is working on new version that works with XML, markdown and HTML. Have tool chain for creating PDFs.

*** 17,000 new leads for PDF documentation in a year for neo4j

How do you deal with documentation from all different places?

  • neo4j - Have a specific build that pulls together all documentation into one place, have separate knowledge base system
  • Twilio has “3-pane view” for code tutorials, may be open sourced in future, alternative now is “Slate” (created by Trippet)

Knowledge base vs Documentation

  • Use knowledge base for FAQ or corner case issues, or ones that are version specific that you connect to via Stack Exchange

What you do when you get a complex PR in?

  • It’s hard to get PR in

Get the content changed is more important than traceability at least in some orgs
Make it really easy to change things
GitHub doesn’t generate different formats
Docs - dedicated vs shared responsibilities

KeenIO everything needs to be documented
Then you can start improving on that
Guides for common things that people want to do
E.g., how to do something - API reference won’t explain that, so you
need a guide
Guides very important early on
API docs and guides
Some guides intended for VP of product, vertical specific guides
Done by marketing
Teaching the same things but in a different way

Intel - focus groups around docs
Do task X
Look how people stumble - see where they go looking, where they are clicking

Google analytics to see whether no one is reaching a page
Web sites are available that check your web site for broken links

New hires need to read the docs - an intern found lots of issues
Good interns can write great docs
Find the least technical person to review the docs

Where are best docs found?
Bugzilla - great docs
Everything in readthedocs

Twilio docs -

Different learning modes
Examples most important thing
Lot of video
YouTube tends to distracts people
One project is hosted at Wistia - great analytics
OStraining stored 2TB for 300 $/m

Thanks to for being the kind sponsor for this forum!