🕵️‍♂️ Doc Detective

Doc Detective (Code) is a tool for testing your documentation and making sure it works for new people to your project or product.

When was the last time someone made sure examples in your documentation actually worked? With Doc Detective you can now make sure that newcomers to your project aren't instantly annoyed by broken examples and instructions.

You can use Doc Detective to run API calls, GUI tests, and even shell tests to make sure that the things you say your project/product does actually work.

With such a wide range of support, just about any code project you're building would probably benefit from using Doc Detective – and your users would thank you.

You should probably automate this (ex. a Github Actions scheduled workflow), and you can make sure that your documentation always stays in line.

This might be a pretty niche use-case but it's certainly Awesome F/OSS and more projects should be taking their documentation (and testing it) more seriously.

🌠 Features

Doc Detective does what it says on the tin (and a bunch more):

• Enables live testing of documentation
• Enables API calls for testing
• Take screenshots or video (!) to generate new documentation
• Analyze test coverate

Very helpfully on their feature page, they list what Doc Detective can't do, which is write good documentation for you 😄.

🤖 As described by AI

The Doc Detective project is an open-source framework designed to keep documentation accurate and up-to-date by testing it directly against the product. It supports UI-based processes and API calls, comparing the documentation with actual user experiences to identify discrepancies. By generating a JSON output, it can integrate with other infrastructure components, helping to detect and correct documentation errors efficiently.

This framework aims to streamline the maintenance of documentation, ensuring that users always have access to the most reliable and current information. By automating the validation process, Doc Detective reduces the risk of outdated or incorrect documentation, enhancing the overall user experience and trust in the product.

📺 Watch this

There's an awesome demo of Doc Detective on Youtube that Manny (the creator of Doc Detective) gave himeself! You can check it out here:

👟 Getting started

While there isn't a docker image just yet, there's an issue to make one:

Docker image · Issue #57 · doc-detective/doc-detective

Run DD without worrying about any dependencies. Simplifies by deployments/CI by providing static images. Would allow WebKit testing on Windows if WebKit on Linux is supported.

GitHubdoc-detective

In the meantime you can install the project with NodeJS and NPM (which is used for managing packages on NodeJS).

Installing with npm

Running Doc Detective is really easy, it's a NodeJS project which can be installed via npm to the command line:

npm i -g doc-detective

You can run doc-detective in your own project with npx:

npx doc-detective runTests

You can also run it on a particular file as well really easily:

npx doc-detective runTests --input doc-content-inline-tests.md

🧑‍💻 Want to contribute?

Doc Detective is a F/OSS project (MIT licensed 🎉), and you can contribute on GitHub:

Issues · doc-detective/doc-detective

Doc Detective is an open-source documentation testing framework that makes it easy to keep your docs accurate and up-to-date. - Issues · doc-detective/doc-detective

GitHubdoc-detective

Since the project is still early, there's lots of impact to be had, you could even drive the open issues to zero (there are only 12 right now)!

📬 Want Awesome F/OSS in your inbox?

We'll send you new articles as soon as they go live.