Once you have lots of projects behind your Office’s back and a bunch of them in progress or yet to come, you start analyzing if anything could have been done better, quicker, and more efficiently.
Each documentation project is unique in its own way, but when you look closer, you can find that most of them follow processes, rules, and collaboration patterns that do not differ that much.
Therefore, we’ve built the documentation assessment process that proved its efficiency and improved the overall quality of our projects, not only at their final stage, but right from the start.
We subdivide our projects into the following groups:
- Short-term projects
- Long-term projects
- Projects without documentation or where the documentation is a secondary activity of developers or other project roles
From the first sight, this categorization may look oversimplified. However, it proved to be quite effective for us. Adding additional categories just adds extra efforts to audit without tangible changes to the audit results.
Documentation projects with the duration of up to 1 year. The duration of such projects doesn’t allow performing a full-fledged assessment along the way. So, to ensure quality on such projects, we:
- Perform peer-reviews.
Frequency: The more often, the better. We recommend sending topics or small sections for peer-review once they are ready.
Purpose: Find and eliminate not only minor typos, but also logic, structure, or workflow discrepancies within the produced documentation. This activity is a must.
- Perform document testing before the final delivery.
Frequency: This activity should be planned at the end of the project before delivering it to end-users.
Purpose: Make sure that the final document is free of layout faults, helps get up and running with the application it describes in no time, and is easy to use and navigate.
- Ask for feedback from the client and end-users.
Frequency for feedback from the client: At the end of each documentation milestone.
Frequency for feedback from end-users: Before the final delivery and during acceptance testing.
Purpose: Provide the documentation that responds to the client’s needs and covers all of the daily end-users’ needs.
- Prepare and present to your team the case study with lessons learnt on the project. This stage helps look on the completed project from another perspective and analyze it against:
- Best practices that proved to be effective on the project.
- Discoveries and innovations applied on the project, their pros and cons.
- Project challenges encountered and ways you’ve dealt with them.
- What would you change if you had a chance to do this project once more and why?
- Lessons learnt
This activity not only helps improve the documentation quality and workflows with every next project we do, but is also a great opportunity for everyone to learn from each other’s mistakes and avoid them on their own projects in the future.
Documentation projects with the duration of over 1 year. The duration of such projects allows for more flexibility and changes in the process once you encounter some challenges. Documentation quality assessment and audit is a good practice that should be planned within the project. Why? Because evaluating a project against certain criteria by an independent expert helps improve documentation flows and quality that is often overseen by an Information Developer who has long worked on this project and simply got accustomed to some project specifics and can’t see the big picture.
Projects without documentation or where the documentation is a secondary activity of developers or other project roles
Why bother about such projects, you’d ask? Simply because we are professionals responsible for all project and company technical content, and as professionals we just can’t allow ourselves to stay quiet when content quality is neglected.
Definitely, on some projects, developers are the best people to produce highly technical documentation. However, very often they do not take it seriously and don’t spend enough time on analyzing the target audience of such content, thus, omitting potential user groups and their needs.
That’s when you come to realize that each documentation project should be assessed against certain criteria. Once you capture and state the best practices and bottlenecks of each documentation project, you feel more secure and know how to deal with such projects in the future.
Documentation audit questions
So, when it comes to basic documentation audit, we assess the existing project documentation against the following criteria.
- Is there documentation on the project?
- Is the UI and features of your tool so intuitive and user-friendly that the users know how to accomplish all the needed actions without referring to documentation?
- Why was it decided not to have documentation on the project?
- Did you offer the documentation services to your client?
- Is there a documentation process established on the project? What are its stages and their sequence?
- What is the trigger for updating documentation? (to make sure whether the documentation process is well established and whether any issues exist)
- Are there any standards for developing documentation defined on the project (Microsoft Manual of Style, Apple Style Guide, Client’s Style Guide, or Style Guide specifically developed for the project)?
- Does the document conform to the defined publications standards?
- Are there documentation templates, styles, and formats defined and used for developing documentation?
- Who is the target audience of the solution and documentation?
- Are the instructions adapted to the audience level of expertise?
- What documentation types are created on the project (User Guide, Administration Guide, Quick Reference, Installation Guide, tutorials, etc.)?
- What documentation deliverables are shipped with the product to end users (printed or online)?
- Is single sourcing and topic-based authoring established on the project?
- Is the information organized in a way that it is easy to read?
- Is the layout of the documentation coherent and consistent?
- Does the documentation contain enough visuals to explain the difficult steps? Are they of high quality?
- Is the navigation usable? Can a user find the needed information in 30 seconds?
- Does the documentation contain or need Index?
- Does the documentation contain or need Glossary?
Help Integration questions:
- What Help type is produced—Microsoft HTML Help, WebHelp, Mobile Help, AIR Help, JavaHelp, HTML5 Help, etc?
- Is the Help integrated into the product? How does the process of integration look like? What is required from an Information Developer in this process?
- Is the Help context-sensitive? How is context-sensitivity implemented?
- How is a certain Help version included into the new solution build?
- Is the documentation under continuous integration on the project?
- Is the documentation process adapted for continuous delivery?
- What tools are used for developing documentation?
- Are any outdated or unprofessional tools used for creating documentation? Why?
- Are any version-control tools used on the project for documentation? If not, how do you mitigate the risk of information loss?
Surely, the list is not exhaustive and may vary depending on the project specifics and workflow. However, it would be a good starting point should you decide that the quality of your documentation needs improvement.
Have you performed lots of documentation audits and assessments and have ideas or lessons learnt to share, please don’t hesitate. I’m really interested to hear about your experience and findings!