Testing
It might seem like final approval from the SME is the last step in your documentation journey. Think again! Testing, and particularly regular testing, is essential for keeping your documentation usable, accurate and complete.
Types of Tests
Testing technical documentation involves a combination of manual and automated approaches. Depending on the tools and knowledge you have available, you can choose the right mix of the two.
- Manual testing works best for subjective or visual issues that tools can’t reliably detect. For example, evaluating the tone of a document or checking image clarity.
- Automated testing is recommended for repetitive or technical issues. For example, link validation or spell checking.
Documentation Testing Checklist
This is a non-exhaustive list of tests you can run in you documentation:
🔗
Check all internal/external links, to avoid broken links or bookmarks.
🖼️
Validate alt text on images, for accessibility.
🪜
Ensure consistent heading structure, to make sure you didn't skip a heading level (for example, H1 followed by H3).
✍️
Spell check, to avoid typos.
💻
Test all embedded code snippets and commands, to ensure that they can be copied and run correctly.
📱
Preview layout on mobile and desktop, to ensure good UX.
🧭
Confirm navigation and TOC integrity, to catch any topics that may be missing from the TOC.
🏷️
Check metadata (title, description, tags), for correct indexing.
🖼️
Check image quality, to have a professional-looking documentation
🗑️
Find unused files, to avoid storing and publishing useless or out of date content.
🗂️
Check file naming, for standardization purposes and to avoid cross-OS issues.
🔄
Update variables, to make sure they apply to the current version.
🎨
Validate adherence to the style guide, for consistency.
📅
Periodically check if old content needs to be updated, to avoid stale pages.
The content-level tests are generally done during the review phase and are detailed in ReviewingReviewing
Some tools that can be used for testing documentation are presented in Documentation WorkflowsDocumentation Workflows.
Next Step
After testing, you can call your documentation complete. The only remaining step is making it available to the users: DeliveringDelivering.