How much detail should we put in the documentation?
What type of information should we include in our documentation, and how deep should we dive into the details? Technical writers make these decisions every day. Sometimes it’s difficult. Sometimes we need to adjust the level of detail after a while, in response to customer feedback. Sometimes we need to bow to the practicalities of time and resources, and omit detail that we’d like to include. When we do that, it’s great to be able to point our customers to an alternative source of information.
A case in point: My previous post is about a new site that publishes advanced tips for Confluence wiki. At the moment, the site contains tips and tools contributed by Graham Hannington as the result of months of investigation and design. Graham is a customer and user of Confluence. Up to now, he has been sharing his information in comments on the Confluence technical documentation. Many many people have benefited from his work. But comments are not the best way to publish structured, indepth information. Graham was looking for a better place.
After consultation with the Confluence product managers, I created the wiki space for advanced tips. Graham has started adding information, and I hope other people will too.
For the record: The new wiki space is not owned by or monitored by Atlassian. It’s on my own wiki, although hosted on an Atlassian server.
Why not part of the product documentation?
Why didn’t we put such information in the Confluence documentation itself, rather than on a separate site?
One reason is, of course, that the information is the product of Graham’s hard work. Graham, and other dedicated contributors like Shannon Greywalker, have over the past many months added comments that have educated the Confluence development team as well as other readers of the technical documentation. Much of what they have brought to light is new to everyone. It’s good to provide a site where people can add information and have their names displayed as authors of the content.
Still, the question arises: Now that Graham and others have brought so many details to light, and contributed so much to the general understanding of the editor and the storage format, should we include such information in the product documentation?
We’ve decided that this level of detail is not suited to our core documentation. It’s just not something that we can commit to maintaining, given the small number of technical writers available. Our primary audience for the documentation will not need this level of detail.
But the information is extremely useful. There will always be people who use a product to its utmost, challenge its boundaries and bring bright new inventions to it. Often, especially when the product is a wiki, those people are technical writers!
Pointing people to other sources of information
So, if people are producing such a wealth of information that is useful to other customers too, but we can’t put it into the documentation, what can we do to make sure people get the information they need?
One solution is to provide a question-and-answer forum, such as Atlassian Answers. This is excellent for community involvement and for specific questions with short answers. It doesn’t work for structured content, or content that needs to be maintained.
Another solution is to provide a separate site where people can contribute and benefit from information that’s specific to a relatively small audience. The wiki space for advanced tips is such a site. The advantage is that it’s a wiki designed for technical documentation, where people can contribute and maintain structured information.
How can we let people know about the new site? We need to link to it from the product documentation, tweet about it, blog about it, and generally spread the word.
We have a page in the documentation called Tips of the Trade, where we link out to “how to” blog posts and articles written about the product by other people. For short-term social sharing, we encourage people to tweet their hints using a specific hash tag (#ConfluenceTips, in the case of the Confluence product) and we show those hints in the documentation too: Tips via Twitter.
A case where we changed our minds about what to include in the documentation
When the team first published the Confluence 4 documentation, way back in September 2011, we didn’t document the new XML storage format. The thinking was that people would use the new WYSIWYG editor and would not need to know what goes on behind the scenes.
In short order, customers let the product team know that this was a mistake. Technical writers, in particular, need to know the ins and outs of the storage format. We have an intimate relationship with our content, and need a far greater level of control over it than people who use the wiki for other purposes.
Thus the product team started putting together a comprehensive document about the XML storage format. We’re still expanding it to include information about every macro in Confluence.
Have we got it right?
Is the level of detail right? I hope so. There’s been a lot of commentary about the new editor, the new storage format, and the backstaging of wiki markup. It will be interesting to see how much traffic the new wiki space for advanced tips gets.
What do you think about the decisions we’ve made about the level of detail in the documentation? Have you been through such a process yourself, and have you had to rethink your decisions too?