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?


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 21 July 2012, in technical writing and tagged , , . Bookmark the permalink. 12 Comments.

  1. Shannon Greywalker

    I’m glad that Atlassian tech writers and product managers were responsive to the community feedback on certain points and implemented the advanced editor (for the storage format) and have started on the syntax doc for the storage format. Is it the “right” level of detail? Well, honestly, no. But I’m going to guess this is because in part because Atlassian seems to not actually using a true XML schema, but is instead seems to be using a lot of XPATH code to work with your own storage format. Therefore your storage format is “loosey goosey”. Ideally, your storage format would have been designed with a true XML schema/DTD, and if that were the case, it would be much simpler for the Atlassian tech writers to document that schema/DTD in an XML-standard way.

    And here’s what I feel is a key point: any tech writers who need to understand/work with/debug the underlying storage format for a page will _also_ be conversant with XML. Or they’ll educate themselves fast. And since XML schema/DTD structures are typically documented in a standardized manner, it’s disconcerting and less useful to us when Atlassian attempts to document it in a non-standard, minimalist way.

    I’m a huge proponent of minimalism. I live and breathe it as a tech writer. I’m talking true John M. Carroll minimalism, using practical application of his basic principles from “The Nurnberg Funnel”, plus a few more principles of my own. I understand what Atlassian is trying to do with the current doc for the storage format, but I disagree with that approach. Minimalist principles should not be applied to reference information. Reference information needs to be complete and comprehensive. Documenting only a few macros as “examples” does not help someone who is staring at the XML representation of a _different_ macro and wondering what they can do with the attributes or content model of that XML element to fix a problem. In a situation like that, the target audience needs the full, complete syntax details. There is no other option that will support the use case of the enterprise Confluence expert who is the one everyone expects to fix problems.

    But on a completely different point, I should point out that my 500-user enterprise is still on version 3.5.x and will be staying there for the foreseeable future. There are just so many bugs still prevalent in the new RTE that it’s literally untenable for us to migrate to 4.x and resume licensing. And various features that I’ve asked for still aren’t implemented. (For example, being able to search for specific storage format syntax strings across an entire space or across an entire Confluence instance. Something as relatively simple as that still does not exist, even though literally 7 months ago I went to great pains to explain the typical use cases for this basic ability.

    One other point. The download page for the Confluence Source Editor plugin says “No vendor support”. o.O How can such a tool not be officially supported by Atlassian? It’s issues like this and my preceding point about the loooooonnnnngggg lag time for getting critical functionality back in place, that used to be baseline functionality in 3.5.x and earlier, that make me tell my enterprise’s stakeholders: “it would be a huge mistake to move off of 3.5.x”.

    Which brings me to my final point. The target audience for any doc is never the 95% of your user base. Most users never look at doc. We tech writers should understand this. The target audience for any doc is the 5% of your user base who are the “power users” in the business units, or the IT admins in the IT department. That’s pretty much it. Our target audience are the people that everyone else goes to and asks “how do I….?” It always irks me to to see a product manager (or CEO.. no, I’m not naming Scott Farquhar specifically, no, I’m not) defend a lack of features or a lack of documentation by saying essentially “but we hear great things from our 95% of end users.” Hey, that’s really great that some other CEO or beleaguered IT manager sees a bullet point on a set of release notes that says “no more wiki syntax! your users now only need to interface with a spiffy RTE!” and sends a congratulatory tweet or email to Atlassian. But these folks aren’t the ones who have to get the real work done. These folks aren’t the ones that have to make all the pages work and all the spaces look consistent and answer all the “how do I?” or “why did it break my page?” questions.

    • Hallo Shannon

      It’s cool to have you dropping by. Your blog posts about minimalism, on the now-defunct Greyfiti blog, were one of the factors that got me really excited about tech writer blogging.

      You’re right, in that there is no XML schema or DTD for the Confluence storage format. Yes, that would have made the documentation task easier.

      This part of your comment is exactly what I wanted to discuss in this post:

      The target audience for any doc is never the 95% of your user base. Most users never look at doc. … The target audience for any doc is the 5% of your user base who are the “power users” in the business units, or the IT admins in the IT department.

      One of the things we’re constantly pressed to do, is to “simplify” the documentation. Of course, there’s a world of nuance in the word “simplify”. What does it mean, and for whom should it be simpler? Anyway, one of the ideas I’ve been toying with is to remove all the middle-level documentation: All the “click here”, “do this”, “this screen will appear” type of stuff. Instead, focus on overviews (domain- and task-focused) and reference documentation.

      Cheers, Sarah

    • Hi Shannon, I definitely agree with your analysis here. From my point of view as a very technically detailed person, I am going to really miss the Wiki Markup Editor, but on the other hand I am setting up a Confluence site for a very non-technical workforce (the 95%) and I am insisting that they go to Version 4 so we don’t end up having any issues where people say it’s too hard to use.

      I also agree with your point that this Wiki needs to be inside the Confluence documentation, as a reference topic. I found it strange that such important information would be in a separate wiki.

      Also, thanks to Sarah for the reply to this comment and pointing me to your Greywalker Method wiki. That wiki is what I was looking for (but did not find) before I created my very large wiki based help document. I had included a number of the concepts such as reusable content, blocks etc, based on Sarah’s writings but I had not gone to the minimalist level of no screen shots, no sequencing etc. I will really try to do that next time.
      Thank You!

  2. Interesting and thought-provoking post, Sarah.

    Got me thinking about how we do things in my company…namely, that maybe we should consider pointing people to other sources of information on our product.

    Our technical documentation has little-to-no reference to available knowledge outside of our domain. And that’s without even mentioning use of Web 2.0 tools (Twitter, blogs, etc.), which aren’t utilized for documentation needs.

    I’m going to mention the ideas that you raised here and see what happens.

    Wish me luck!


  3. grahamhannington

    You’re right, in that there is no XML schema or DTD for the Confluence storage format. Yes, that would have made the documentation task easier.

    There is, to my knowledge, no “official, authorized, published-by-Atlassian” XML schema or DTD. I really wish there were. But there is my attempt. I’ve received email from Atlassian customers indicating that this has been helpful to them. One recent email made my day, if not my year; certainly, it justified the effort.

  4. grahamhannington

    (The email that I’m referring to – the one that made my day – was from an Atlassian customer, not Atlassian.)

  5. grahamhannington

    Thanks again for making that “advanced tips” Confluence site available, Sarah. Much appreciated.

  6. I have a question…how much do I document in an API level documentation where for a particular operation there are more than 50 elements that can be used to execute that operation? There are only 5 elements that are mandatory.

    • Hallo Shweta

      I’d say that your reference documentation should include every single element. The reference documentation should be auto-generated from the code. Often, it’s the optional elements that are more interesting, because they offer functionality that people need and that is less obvious than the mandatory elements.

      In the human-written documentation, I’d suggest a few tutorials that tackle the most common use cases and show people how to use the mandatory elements and the relevant optional elements.

      Cheers, Sarah

  7. Thanks Sarah! We were contemplating on the use case approach lately.

Leave a Reply

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

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

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: