The Product is Docs: Writing technical documentation in a product development group [by Splunk]

The documentation team at Splunk have written their own book called The Product is Docs. It covers the most important aspects of documentation for software development product teams. We read this publication in the first Write the Docs Northwest book club group, following along with the virtual book club in the Write the Docs Slack group.

The primary audience for the book is information developers, but also documentation team managers and members of the product team. The overall message of the book is to treat the documentation like you would the product.

The emphasis is on technical writers to advance their cause and push for complete, technically accurate, and customer-centric documentation for the software.

We’ve included some summaries of particular chapters that we enjoyed the most. The book references other publications, including Every Page is Page One by Mark Baker and Design for How People Learn by Julie Dirksen.

Agile technical writing

“With direct participation [in the scrum team], you establish the documentation function as a peer to engineering, UX, and QA. The approach improves the standing of the documentation team in the eyes of the other functions.” 

Splunk is an agile development team and the book provides many in-depth recommendations for technical writers working in Agile.

The chapter begins with referencing the Agile Manifesto, which promotes:

• Individuals and interactions – Reach out to team members for documentation purposes, try to work in the same physical location as the scrum team, and join their communication channels.
• Working software – Refers to working software over detailed engineering specifications, but specs are essential and should be updated regularly throughout the agile lifecycle. Also, customer documentation is an essential part of “working software”.
• Customer collaboration – Develop a regular customer feedback loop, use chatrooms, user groups, online forums, conferences, direct feedback, Customer Support, and UX research.
• Responding to change – Continuous documentation development. Agile can proceed without detailed plans for each feature, but you should adjust your plans depending on continuous customer feedback. If you write your first words about a feature after development is finished, then you are not agile. 

Agile implementations are different in every company, but technical writers typically attend iteration planning meetings, scrum standups, and iteration demo reviews.

Agile for technical writers is about relationship-building – organize face-to-face discussions, use the company’s standard development tracker for documentation, and make your work visible in the same tickets as development.

Documentation tied to a specific feature works best for scrum. Troubleshooting, release notes, migration/upgrade, end-to-end tutorials, best practices, and some API work, does not fit well with scrum.

Audience for documentation

“Reliable and accessible product documentation requires thorough product knowledge. It also depends equally, if not more, on knowing your audience.”

Audiences for technical writing are rarely defined explicitly, but there is great value in taking the time to accurately pinpoint your audience. Reliable and accessible product docs depend on knowing your audience. You need to identify your user goals.

Knowing your audience helps you decide what writers to hire, and helps you identify learning opportunities for current writers. It benefits users, in helping you decide what delivery format to use for docs, and content organization.

Start with any available audience information that you have, possibility from other teams like marketing or the product team, and other internal docs. Work with colleagues who are user-facing and communicate directly with users yourself.

Work with your colleagues to come up with an audience definition, and revisit audience definitions and assumptions regularly.

Tools and Content Delivery

Here’s a quote from the book that we very much believe in here at KnowledgeOwl: 

“There is no way to recommend a specific content delivery tool, authoring platform, or content management system without knowing a pile of information about what the information deliverables need to do and how a doc team intends to operate.” 

One tool that is a perfect fit for one team may be hopelessly inadequate for another. And there is no “one ring to rule them all” when it comes to choosing a documentation tool. You have to assess what problem you want to solve and then look for a tool that comes closest to fitting your description, and one that you also enjoy using. It also has to come at the right price!

Splunk itself uses a customization of MediaWiki, the popular open source wiki software that powers Wikipedia (their version is called Ponydocs). 

The authors make a distinction between content management, content delivery, and content authoring.

For content management, ask yourself: 

• Will multiple people create and edit content? 
• How does the tool manage source control? 
• How will your tool manage versions of a document? 
• How will the tool ensure the author is working on the most up-to-date version of the document?
• How does the tool manage versions of a product? 
• How does the tool ensure that readers can access the right documentation for the version of the product that they are using?
• If the documentation is online, how does the tool notify readers that new content is available?
• Does the tool offer any archiving or backup and restore capabilities?
• The authors recommend working with Git for content management due to its ability to manage the source control of code. In the same way, Git can manage files that contain documentation, keeping track of versions and authors. Git can be combined with a lightweight markup language and a static site generator. 

For content delivery, ask yourself: 

• Will the content mainly be available online or offline, on the web, or in a print or static format?
• If your content is online will you need to provide a mechanism for users to access content offline?
• Does the tool ensure that formatting elements like tables and elements remain intact, when converted from online to offline format?
• Does the tool make it obvious to users that they are accessing the right documentation and version of the product?
• Can you publish one article at a time, or are you restricted to publishing sets of material?
• The authors recommend Microsoft Word or Adobe FrameMaker if you’re planning to publish printed documentation.

For authoring usability, ask yourself: 

• Does the tool enable writers to draft documentation that remains inaccessible to users before publication? 
• If your tool is authoring in an online environment, does it have auto-save or otherwise prevent the loss of your work?
• Can authors easily compare different versions of the content?
• Can you easily revert to an earlier version of the content?
• Does the tool offer any kind of workflow management? Eg, can an author write content and then send it to an editor or SME for review?
• Will you be authoring content in a structured format like DITA? Does the tool support and enforce structured authoring?
• How important is WYSIWYG authoring to your content producers? Will they be comfortable working in markdown, wiki formatting, or XML, or do they need to see the content in an interface that displays the material with its formatting visible?
• How does the system manage linking between articles or doc sets? 
• Can you reuse content in the system, and how well would content reuse scale? 
• The authors recommend simpler publishing tools like a wiki, or even WordPress, with WYSIWYG content creation and support for multiple authors. However, you won’t be able to manage your content much more than save a draft for later. You won’t be able to manage versions of the content or create structured content.
• If you have more collaborative needs and a desire to reuse content on a large scale, consider commercial software solutions like MindTouch or Madcap Flare.

For reader usability, ask yourself:

• Does your online documentation display nicely in multiple browsers on multiple operating systems?
• If you convert your content from online to offline, does the formatting remain consistent?
• Is the documentation interface universally accessible? 
• What is the reader experience like when searching for information in your documentation? What’s the interface’s navigation like?
• Does the tool support localization of content? For example, can you translate content from a roman alphabet to a Cyrillic alphabet and still display it? 
• Does the tool display information well on mobile devices if necessary?
• Can the reader interact with your content? For example, through user comments, asking questions, or accessing other help resources?

There are other considerations, like the capabilities for metrics and SEO. In general, however, you are likely to be able to integrate Google Analytics with most online tools to measure performance. 

You might also want to consider integration with other tools, like migrating existing content into the platform. What capabilities does it have for adding extensions, or building your own?

Finally, consider the pricing of whatever tool you choose. Open source solutions are generally free, but they lack technical support and you have to DIY your implementation. Commercial solutions are much pricier but are usually tailored to a particular publication format, market, or industry. 

Working with engineers

“Your relationship with your subject matter experts is essential to your success.”

Technical writing is a relationship business and many of your SMEs will be engineers. It’s crucial to learn to work effectively with the engineering team in order to produce the most thorough and technically accurate documentation.

You need to gain the required knowledge to have a substantive, collaborative, peer conversation with your engineers. If you fail to do so, you risk being marginalized on the product team and your documentation will suffer. Almost any technical domain you need to learn has free resources you can take advantage of.

The authors also recommend preparing in advance for every major conversation you intend to have with an engineer on your team. Make sure you read any personas, use case information, requirements, specifications, and test plans, and familiarize yourself with the terminology.

Make the conversation worthwhile by asking questions like: Why did we decide to build this? Who will use this?

Final remarks

There is a lot more information contained within this book than we've been able to summarize here. It was the Splunk authors’ intention to provide an up-to-date and comprehensive resource for documentation teams – particularly those following the Agile methodology.

You don’t have to read the whole book from cover to cover. It was written particularly to enable readers to dip in and out of the chapters that interest them.

Agile documentation teams need the right tools for their work. Take our knowledge base software KnowledgeOwl for a free spin.