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.