Write The Docs EU — Fintan Bolton — The community wrote my docs!

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Is community–written documentation a good idea? Absolutely. As an example, Red Hat had 6,000 pages of documentation — 1,000 were from the community.

Wikis are powerful:

  • Low barrier to contribute.
  • Instant publication and gratification.
  • Zero learning curve (almost).
  • Editable as plain text.

Pros for DocBook/DITA:

  • Good formats for archiving docs.
  • Rich markup vocabulary.
  • Precise and well–defined syntax.
  • Sophisticated build options (e.g. conditions and profiling, includes and con refs, entities)

What’s the impedance mismatch between the community and corporate documentation?

  • Variable quality (e.g. formatting, style).
  • No versioning.
  • Inappropriate content (stuff you wouldn’t want to support, inaccurate claims, spam)

Synchronizing community and product documentation. Rather than tracking community–generated docs and merging with product docs, track community–generated docs from previous community–generated doc changes, then convert the latest iteration into the product docs. Don’t clobber the work of other contributors, lest you lose popularity. Keep in mind that competitors will use comity–written docs.

In conclusion, integrating community–written docs is a big issue, and involves more than a conversion tool. On the flip side, there can be big rewards.

Fintan Bolton is from Red Hat.

Published by

Bryan Villarin

Bryan is a Happiness Engineer at Automattic. He's also a photographer, card magician, and cat whisperer. (Thanks to my friend and colleague Steve Blythe for the sweet photo!)

Talk to me, Goose

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s