Understand the Purpose of These Manuals
When you’re developing an application with complex functionality, you need to provide support documentation for future users and for the developers who will be maintaining it.
This is the reason why you and your colleagues will be creating a user manual and a maintenance manual.
The purpose of the user manual is to explain how the application works to future users.
For example, how do we launch the simulator to check the status of the rockets?The maintenance manual exists to explain all of the actions developers will need to take to ensure that the application continues to work correctly over the long term.
Application libraries to be updated, how to manage backups and bugs, etc.
For all these reasons, it is important to create clear and easy-to-understand content for the future consumers of these documents.
Strive for Clarity in Your Manuals
You can apply a few principles to ensure that your manuals are correctly understood.
Lead a Workshop
With help from developers and testers who know the application backward and forward, we can organize workshops to define a structure that makes sense to everyone. After the workshop, everyone will be responsible for writing their section within a fixed timeframe. In your role as coordinator, you’ll need to check that the writing meets the required standard. This includes phrasing that’s easy to understand and process steps that are well defined.
Choose an Online Resource
To accommodate future changes, you should choose a manual that can be accessed online, like a wiki. This is a handy format that allows changes to be made at any time if your application is updated.
Tools such as GitBook, Confluence, and Read the Docs are specifically designed to host software documentation.
Check Your Manuals for Completeness
When dealing with a critical application, there’s no room for approximation in your documentation. Your manuals need to be produced to a very high quality. Your users have high expectations and want to use the application’s full functionality. Unfortunately, we still find numerous cases of bad writing, which can impact on the work carried out by the reader. For this reason, I suggest you apply a number of golden rules to help you provide quality documentation:
Adopt a simple structure.
Use simple language.
Use relevant visuals and screenshots.
Provide real-world examples.
Make ample use of white space in page formatting.
Publish on an intuitive, high-quality platform.
Break your instructions down into clear, numbered steps.
Use meticulous proofreaders to guide you.
Proofread the manual several times and correct any mistakes.
Check that the manual is kept up to date on a regular basis.
Ask for user feedback to help improve it.
Ensure High-Quality Manuals
To ensure you produce a high-quality manual, make sure you:
Present your content in a well-designed, intuitive way.
This might seem like a minor point, but when a manual is nicely presented with attractive fonts, well-structured information, and colored elements, this will make it more enjoyable for the user to read.They will understand the information better and spend more time reading your documentation to get to grips with the tool.
On some projects, I’ve been tearing my hair out while reading documentation because it’s been so awful. By considering this aspect, your hard work will be greatly appreciated.
Provide high-quality indexing and navigation.
The challenge when using a manual is to be able to easily find the information you need. I don’t know about you, but when I waste a lot of time looking up a simple piece of information that is supposed to be contained in a document, I get pretty impatient.A reader’s attention span diminishes over time. I recommend you provide a detailed document map that’s always visible, along with a great search engine. This will provide a seamless search experience to the people using your manuals.
Over to You!
Background
The leadership team has given you the crucial role of producing a comprehensive, well-structured user manual for the rocket-testing application, to be created on the Notion platform.
Instructions
The success of this manual depends on the content being clear and accurate. Here are the key steps to follow to complete this task successfully:
Assign contributors: Based on your team members’ skills and knowledge, assign specific sections to the relevant people for them to write. For example, a telemetry expert would be ideal for writing the “Diagnostics and Telemetry” section.
Manual structure: Create a skeleton structure for the manual in Notion. This should reflect the various software functionalities and sections, such as the rocket-launching system, diagnostics, flight simulation, etc.
Add content: Once you have your outline structure for your manual and you’ve assigned contributors, add the supplied textual context to the appropriate sections. Ensure that each piece of text is consistent with the section header.
Let’s Recap
For complex applications, it’s essential to provide user and maintenance manuals. These documents guide the users through the application functionality and help developers to provide ongoing maintenance.
To ensure that everything is covered in the manuals, it’s a good idea to base them on the specifications, organize workshops with developers and testers, and use an online platform to host the documentation to allow flexible updates.
High-quality documentation should have a simple structure, clear language, relevant visuals, real-world examples, and regular proofreading to ensure it remains relevant and up to date.
Intuitive presentation, design, data indexing, and an efficient document map are vital to ensure that the user manual is enjoyable to read and easy to navigate.
After fully documenting and creating the relevant manuals, let’s move on to a key step at the end of the project: running the project post-mortem. We’ll explore how to extract the important lessons learned from this process.
