HackMD
Doc Inspector Test Drive
Goal: Set up the Doc Inspector tools, use them to inspect some docs, report back
Stretch goal: Find something to contribute back to the project: docs, bugs, enhancements, whatever…
About Doc Detective
What is Doc Detective?
Doc Detective is doc content testing framework that makes it easy to keep your docs accurate and up-to-date. You write tests, and Doc Detective runs them directly against your product to make sure your docs match your user experience. Whether it’s a UI-based process or a series of API calls, Doc Detective can help you find doc bugs before your users do.
Doc Detective ingests test specifications and text files, parses them for testable actions, then executes those actions in a browser. The results (PASS/FAIL and context) are output as a JSON object so that other pieces of infrastructure can parse and manipulate them as needed.
What can Doc Detective do?
Doc Detective can do a lot, especially with a bit of creativity.
Test documentation for accuracy/freshness
Doc Detective’s core strength is the ability to systematically check each and every element of your documentation for adherence to the reality of your product. Each of the following items can be inspected:
- Existence of page elements
- Written text (such as a heading or a button string)
- Screenshots
- Links
- API endpoints, functionality, and responses
- Anything you can write a script to verify
Generate screenshots or video to accompany documentation
When Doc Detective runs tests, it can take screenshots and make recordings. You can include this media in the documentation to complement written processes, aiding the readers who prefer visual media while making sure your videos and images are up-to-date.
Generate tests when updating documentation
After you write new documentation, Doc Detective can scan it and generate the necessary tests to verify its accuracy.
Analyze the test coverage of your documentation and suggest solutions
Doc Detective ties specific tests to each line of your documentation. As a result, it can identify portions that are underserved and provide recommendations on next steps.
Feedback:
- Avoid telling readers how 'easy' something is. [1]
- That first test result is a bit of a missed opportunity. I like to know what's going on in the background.
- What's 'npm i' do?
- Really wish I knew what was happening…
