10 Tips for Structuring your Product Documentation

Product documentation is often an afterthought. Developers primarily focus on creating a cool product. They can’t wait for users to get started with it, often with bare minimum documentation, completely ignoring the user’s point of view. In today’s digital economy, customers can choose from an abundance of popular, well received products that have set the customer expectation bar much higher. Many of these competing products are not only aesthetically designed, easy to use but also come with professional quality documentation and self-help. Your prospects may be unfamiliar with your product’s functionality or its APIs but they are well-aware, well informed and well empowered by such offerings in the market.

Imagine the kind of customer experience your bare minimum, un-edited transcripts of developer work logs and ‘Readme’ notes would offer to such prospects, who have ample choice out there from your competitors?

We humans depend on our cognitive fluency to read and process information, understand what the presented information means and how it can be utilised for carrying out specific tasks. Well-structured documentation enables better customer experiences through cognitive ease rather than challenging the cognitive skills of product users. Cognitive ease refers to documentation that is easy to read, intuitive to navigate and is practically useful to those with little or limited experience with the product. Getting the product document structure right not only makes a huge impact on customer experience, but it can also help unblock users quickly and encourage them to use the product more effectively.

If you are a technical writer, or a developer, trying to bridge the developer-customer gap with effective documentation, this blog post offers some tips to structure, plan, write and deliver documentation that is useful to the product users.

1- Categorise information

Categories make it easier to segment information. Before you think of structure, you need to identify the kind of information that your documentation represents. Is it project or technical documentation or is it product documentation. Project documentation is primarily meant for collaborating developers who help in evolving the product. This information may be internal to the product or shared with other external collaborators, especially in open source context. Also, it could be used to train product sales partners and marketing teams. Product documents are typically meant for the end users and need careful structuring from user’s point of view and not from developer standpoint. Structure is also dependent on the content type or category. For example, theoretical documents such as key concepts related to the product, API references need to be structured differently from practical information such as tutorials and How-to guides.

2- Align with your target audience

Identify and understand the specifics of how most of your documentation users will typically utilise your content. This is a big factor in structuring documents. The structure needs to align with the information access workflows that your target audience find easy to access and navigate the requisite content. Think about the logical information flows that your content reader would traverse to accomplish something specific. For example, a user may try to locate a tutorial to do something using your product to solve a real-world problem. Or she may start with a troubleshooting or a how-to guide, come across an API or command in one of the steps and then look for details of that API.

3- Provide an entry point that highlights key parts of your product documentation

Placing all information relating to your product through a well-designed landing page is a smart way to create an entry point for users that is easy to access. Following are some of the key components of product documentation that can be made accessible via a landing page. These help users in understanding how your product is useful in their context before they decide to use it.

• About — What does your product do and what problem does it solve for the users?
• Access — Is the product deployed on the cloud, or on premises? How to obtain credentials to access it on cloud? Does it require any setup or configuration? What are the recommended ways to access the APIs or code functionality?
• Usage — How-to guides, tutorials, user guides, FAQ, troubleshooting guides, API references
• Resources — Templates, Examples, case studies highlighting how other users or projects use your product, technical white papers, links to documentation related to older version of the product, etc.
• Support — How can users get support in case there are issues in using the product? Are there any forums, communities or other channels that can be useful?
• Other — License, Contribution guidelines for products that are open to end-user collaboration for product or its documentation.

4- Create a documentation plan

Product documentation is crucial to knowledge transfer. Its purpose is to clearly list your product specific objectives that can guide you towards creation of useful product documentation. A documentation plan can effectively streamline technical writer and product developer interactions and assist in anticipating issues related to product usage. This plan must address both — how information is organised (Information Design) and how users access it (Information Map). Information Design addresses how the product documents look in terms of layout, what is included in terms of content, and the hierarchical structure of information. Information Map governs the order in which information is presented, the top-down information flows, how users move around and navigate and which parts of the content or subsections are linked or connected, etc. A documentation plan guides documentation structuring by addressing the following aspects:

• Actionable insights. These are gained from audit of existing product documentation to understand what can be leveraged, what is redundant, outdated or missing in terms of user information, which older versions need to be available, what are user pain points related to existing product documentation, etc.
• Templates and Style guides. In documentation, keeping contiguity in terms of style, tone, and presentation is very important for consistent design and structure. For a new product, you need to follow some basic guidelines that are relevant to your industry, users and other product stakeholders. In case of new version of a product already in use, make sure you stick to templates and style guides that are pre-decided for your product or those that your users are familiar with.
• Documentation Tooling. It helps to streamline well-structured documentation creation if your tools and techniques get well with the product development and documentation processes. This is crucial for information exchange and updates to content through team collaboration. It can save a lot of conversion, formatting and translation times later in the documentation development process.
• Hosting. The plan must cover where your documentation will be hosted. Is it publicly available or restricted access?
• Feedback. In case of a new product, or a first release, the documentation plan could also include a mechanism for end-user feedback or ways to identify inaccuracies or missing information that new product users require.

5- Streamline the Navigation Structure

Well-structured documentation makes it easy for readers to traverse the information that they are looking for. Documentation navigation flows gives technical writers the control over how various target audience interact with the product documentation. This helps to align the physical structure of the documentation according to the various reader types such as new users, seasoned users, product contributors and others. Clear and precise navigation structure helps readers locate information quickly. Navigation structure can be customised to suit various reader persona types with mechanisms such as separate tabs for different audience, blocks of highlighted code, rich media content including videos and images, or enabling ‘pdf’ based printable downloads of selected information.

6- Dealing with Static as well as Dynamic content

Documentation evolves over time and there are both static and dynamic nuggets of information that technical writers deal with. You need to identify and logically group dynamic documents while ensuring static documents are relevant to help new product users. Too much static content can be confusing and clutter your documentation set, making it difficult to maintain. Dynamic documents are the ones which evolve with the product, whereas the static ones typically refer to dated or original concepts that don’t change across new versions of the product. Technical documentation is a living, breathing beast that needs regular maintenance and updates. It is useful to structure the content such that updates are easy to execute and validate without impacting the entire documentation set.

7- Keep Versioning Handy and Simple

Identify product documentation versioning requirements so that it is easy to organise the documents according to product version. Versioning enables users to access product documentation according to the version that they are using. Grouping product information as per product version not only helps end-users find what they are looking for quicker, but it also helps in maintaining the documentation. Version based grouping also helps to inform product users about using a dated product version, if they have not yet moved to the latest version of the product. It keeps them sensitised to newer product features and capabilities gently encouraging them to make an informed decision to upgrade. For more on how you can manage product documentation versions, see here.

8- Divide, Rule and make it interesting for the readers

A flat information structure with just text may be harder to understand and an eyesore when you must sift through reams of information. Instead of letting the reader’s interest wane with long boring text, use chunks of easily consumable information that is presented using smartly chosen rich media in logical blocks, as relevant to the topic being covered. For your reader’s cognitive ease, you can use techniques offered by DeveloperHub.io such as highlighting pieces of information (code, callouts — notes, information, tips, alerts) or seamless integration of images, videos, linksand more.

9- Fast and Precise access to relevant information

This requires careful page structuring and keep information accessibility as your top priority. Your product documentation page load time can tilt the decision in favour of a competitor’s product. You need to understand the impact of page load times in the context of your information structuring based on information type. For example, technical command references or API references are usually long pages. In their case, single longer running page content is more usable than same content spread over multiple pages. This is because it takes time to load and could frustrates readers. On the other hand, How-to and tutorial kind of content need focussed step-wise accurate information that can be logically broken into distinct steps via separate pages. Choose page structuring wisely, depending upon the time required to execute the step in a tutorial and overall scope of the information.

10- Make information layout intuitive

If you have taken care of most of the tips above, here is the last one. Avoid jumps, non-contiguity, and the ‘hoops’ that a reader needs to overcome, such as multiplicity of clicks, to access the desired information. Intelligent use of documentation tooling constructs such as categories can help in logical grouping of related information. You can deploy parent pages, sub-pages to segment information for clarity. Use more than two-level tree structure access sparingly as deeper nesting needs more clicks and reader attention span and interest wanes as the number of clicks increase to reach the desired information.

It doesn’t matter how good a product is. If it is not intuitive to use or if the documentation is there but not useful for the target audience, the product will not be used effectively. Well-structured documentation can significantly lower the product adoption barrier and improve product experience.

Get your Product Documentation ready with DeveloperHub.io

DeveloperHub.io is a managed service to create developer hubs (developer portals) containing product documentation and API References. We provide you with a top-notch user experience where you've got all the tools you need to have your developer hub up and running in no time, using the industry's best standards.

Do you think your product documentation is well-structured? We would love to hear about your experiences with well-structured documentation.

Written by Shaloo Shalini for DeveloperHub.io.