Introduction to Doc Detective
Validate your content with Doc Detective:
NPX
Docker
See the Installation guide to get started. Come chat on Discord.
What’s Doc Detective?
Doc Detective is a doc content testing framework that simplifies the process of keeping your docs accurate and up-to-date. You write tests, and Doc Detective runs them directly against your product to ensure 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. It outputs the results as a JSON object, carrying PASS, FAIL, WARNING, or SKIPPED plus context, so other infrastructure can parse and manipulate them. Tests are marked SKIPPED when they can’t run in the current environment. That happens when a test specifies a browser or platform that doesn’t match the system running it.
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 systematically checking every element of your documentation against the reality of your product. You can inspect each of the following items:
- Existence of page elements
- Written text (such as a heading or a button string)
- Screenshots
- Links
- API endpoints, capabilities, 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. Include this media in the documentation to complement written processes. It helps readers who prefer visual media, and keeps your videos and images up-to-date.
What can’t Doc Detective do?
It’s important to know your limits, and Doc Detective’s too.
Write your documentation
Doc Detective doesn’t scan your code or generate documentation. It verifies the accuracy of documentation by running tests against your product.
Write your code
Doc Detective can’t write code for you.
Who is Doc Detective for?
As an open source and accessible project, Doc Detective is for anyone who’s interested. More specifically, here are some groups who could benefit:
- Small teams: There’s often limited personnel or budget dedicated to a project, and documentation often gets deprioritized as a result. With Doc Detective, you can spend less time reviewing published documentation and trust that it’s still functional and accurate for the end user.
- Large teams: The more people you have contributing to a project, the faster it can change shape. In cases where development is outpacing documentation, Doc Detective keeps a watchful eye on the changes made and notes any inconsistencies.
- Anything in between: A team of one or of one thousand can find a use for Doc Detective. When it comes time to address your project’s documentation, Doc Detective eases the burden and brings consistency and accuracy to the end user.
Next steps
Want to take Doc Detective for a spin? Get started.