I’m at Write the Docs today in Budapest and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Fintan kicked off the longer talks after lightning talks. He works as a writer at Red Hat and focused on where community documentation meets product documentation. His talk explored whether a community could write your proper, official documentation.
As writers we never have enough time to pursue all the projects we want to accomplish. The community Fintan works with has written about 1,000 pages of the 6,000 total pages of documentation. While the community’s documentation lives in a Confluence Wiki the official Red Hat documentation needs to live in DocBook. The community wiki gives a low barrier to contributing an pairs instant publication with plain text editing. DocBook, on the other hand, is more complex to edit but presents good formats for archiving docs and has a rich markup vocabulary.
They rely upon a commercial tool to convert the Confluence wiki information to DocBook. Simply converting the content, though, isn’t enough. There’s still a distinction between community documentation and corporate documentation. What they run in to in this process is:
- Variable quality in community docs. There might be different formatting, styles, or more.
- Community documentation frequently has different versioning.
- Community documentation may have inappropriate content, links, and more. Things like untested features you’re not yet supporting.
Given that, Red Hat goes through a process for synchronizing their community and product docs. They use a separate repository for each and maintain a series of snapshots for both sets. These are stored in their version control system. Ideally these sets stay close to each other. In reality, though, after a couple releases the two sets diverge quite a bit.
What they’ve done is simply compare the community docs with an automated diff tool and then merge those changes in to the current product docs. It trades a bit of manual labor for less divergent doc sets.
Ultimately bringing in community documentation from open source projects is tough, but worth it. The different formats, tone, and necessary information can take time to sort out but eventually gives you a much stronger base to work from.