Six-Step Approach to Developing Software User Documentation
A software product is never complete without its user documentation. If you work in a high-functioning agile team, you will know that the documentation development process is also a team effort just like everything else.
In this article, let’s look at a six-step approach to developing user documentation, which covers all phases of the documentation development lifecycle (DDLC) with a special emphasis on team collaboration.
It’s a common misconception that good user documentation is all about the ‘writing’. If the documentation is to be successful, we must focus enough on all phases of the documentation development process.
Let’s get started!
Plan
This phase is generally about Analysis and Design. However, let’s also use this phase to prepare and organize the team.
#1 - Analyze Requirements
- Gather information about all the features planned for the current product release. Clearly understand the ‘what’ and ‘why’ aspects of each feature.
- Analyze how each feature affects different users that will interact with the product (know your audiences!).
- If you are following an agile methodology, ‘user stories’ are always helpful at this stage.
#2 - Design the Documentation
- Once you understand the features that will be developed, plan the overall structure of the documentation (information architecture) and break down the user goals and tasks that the documentation should cover.
- Plan the types of content you will need. Typically, user documentation covers five to six types of content: quick start guides, tutorials, how-tos, concepts, references, and sometimes samples.
- Also, think about progressive disclosure of information. Sometimes, you need to start with a simple user interface description and then cleverly guide the user to follow more comprehensive documentation.
#3 - Prepare your team and resources
- Make sure you have all the writing tools and resources you need. If you don’t have enough writers, make sure that other members (developers, UX engineers, QA engineers, etc.) can effectively contribute.
- Each team member should be aware of how they should contribute to the documentation. Make sure you allocate the required amount of time from each of these team members for the documentation tasks.
Let’s discuss documentation planning in detail in a later article.
Write
In most agile organizations, writing is also a collaborative process. In some cases, the technical writers do all the writing and sometimes multiple team members contribute to a single piece of writing.
For example, the engineer who develops a feature produces the first draft of a single document, which is then passed on to a technical writer for improvements and additions.
During the writing phase, the main objective is to follow technical writing best practices and guidelines. Make sure you either have an in-house style guide or an industry-standard guide on the grammar rules, formatting rules, tone, voice, etc. that you use in the writing.
Writing guidelines are fun, but they are not always easy. For example, I hope you notice the pain I am going through to write this article in short paragraphs dedicated to a single idea. It is a best practice called ‘chunking’!
Let’s discuss writing practices and documentation guidelines in detail in a later article.
Test and Review
Documentation testing and reviewing are part of product testing. Just like you do unit testing, integration testing, QA testing, etc. for the product, the documentation should also be thoroughly tested and reviewed.
Make sure you cover the following aspects of documentation quality during this phase:
You need to carry out different types of review to achieve all three quality goals:
You may notice that different skills and competencies are required to test and review all aspects of documentation quality.
True! You can always have one or few persons (possibly your technical writers) to do all of the above. However, this phase will be most efficient if your team collaborates. For example, try to align documentation testing with the product QA process.
Publish
Publishing is the process of making the user documentation available to the product users. This may mean you are taking your online documentation live, hosting your PDF manual for download, or delivering the printed manual (a bit old-fashioned but still possible).
At this stage, be sure you have a well-defined release checklist. Go through the checklist to make sure you have covered everything. If you find anything out of place, address them immediately (depending on the severity of the issue) or make a note to fix them in a future iteration.
Monitor
This is another aspect of documentation development that we can often overlook. Once we have delivered, we need to look back at what we have done and learn from it.
If your documentation is online, there are many tools, such as Google Analytics and heat maps among others, to gather information on how your users are engaging with the documentation.
Pay special attention to things like discoverability (how users find your content), the most popular pages, the time users spend on each page, what users are clicking the most, etc.
If you have access to users, try to run some surveys and organize group sessions to talk to people and get feedback. Also, you can investigate online community forums and see what people are saying.
Plan for continuous improvement! Remember that there will be another iteration or another documentation project to take up.
Maintain
Just like monitoring, documentation maintenance is a post-release activity. If your documentation is online, the key is to make sure your content is always available. You need to have a sound infrastructure to achieve this.
What’s Next?
In this article, I have briefly introduced the six main steps of developing user documentation.
In the next edition, I hope to expand on the two most exciting phases of this process: Planning and Writing.
Stay tuned for that!