Meet the Maintainers for a chance to win a GitHub Shop voucher: @hawkeyexl, Doc Detective #153593
Replies: 7 comments 6 replies
-
|
Hi @hawkeyexl, I enjoyed reading your story and checking out your project. I see you've used some automation tools to help manage Issues and provide support to Issue reporters. Can you talk about your experiences there and if there are other tools you wish you had to make running an open source project easier? |
Beta Was this translation helpful? Give feedback.
-
|
Hi @Jeffrey-Luszcz. Frankly, my experience has been mixed. There are times that these issue bots are helpful, like when they learn to assign proper tags and labels to issues and PRs or actually look at the docs to respond to users thoughtfully. Then there are times when a user logs a valid bug, but the bot tells them they're wrong because the docs don't say it's a but. Understandably in these cases, neither the user nor the maintainer care for the bot in these cases. My biggest hurdle is in better planning out releases. If I could tell a tool, "Hey, I need to update this schema. What's the impact?" and it could find all the necessary downstream changes and optionally open issues and assign those issues to a project? I'd be in heaven. |
Beta Was this translation helpful? Give feedback.
-
|
@hawkeyexl, thanks for sharing your journey with Doc Detective. Your approach to turning docs into automated tests is truly inspiring. I believe integrating advanced CI/CD dashboards and smart issue triage tools could further streamline project maintenance. Do you see these tools complementing your current workflow? Looking forward to your insights! |
Beta Was this translation helpful? Give feedback.
-
|
Hey @williamhnyohei! I agree 100%. Analytics dashboards and metrics analysis are within the long-term scope of the project (AKA I've been working on some early plans recently). As for issue triage tools, there are already some solid ones in development, and while Doc Detective might lean into that space eventually, I'd rather play to my strengths and gather as much context as possible before handing off the findings to other, more specialized tools. I could easily see first-class integrations with some of these tools happening. That said, there are some areas that Doc Detective can and will integrate some smarts. Whether that's to assist in step detection when parsing documentation source content, suggesting steps based on user interactions within a browser, or using local LLMs/VLMs to try to course-correct a test that's gone awry, there are many improvements to be made. :) |
Beta Was this translation helpful? Give feedback.
-
|
Thank you so much for sharing your thoughts! I really appreciate your insights and the direction you’re taking with Doc Detective. It’s exciting to see how these ideas can improve our workflows. Keep up the great work! |
Beta Was this translation helpful? Give feedback.
This comment was marked as off-topic.
This comment was marked as off-topic.
-
|
Morning @hawkeyexl! Another great project that I didn't know about 😅 I'll definetely try that later for my college projects!
What were some great decisions you had to make while maintaining this project? You ever had a moment like "which direction should I go with this" or "Should we actually include this feature right now"? |
Beta Was this translation helpful? Give feedback.
-
|
@Salgado2004 The most difficult part of this project is deciding which areas to invest in at any given point in time. I easily have enough work here for a lifetime! But I always come back to the "why". Why am I developing the project? To help even the least technical content owner be confident in their docs. If I ever need to decide between to courses of action, that purpose usually helps focus me. As for a great decision I've made, the biggest one I can think of is how to handle automatically detect test statements from documentation content. I've tried going at this a few different ways a few different times. In v1, I toyed with it but didn't enable it. With v2, I really wanted it on by default so that people could have more tests with less effort, but it wasn't fully there, and there were more pressing priorities. I made it an optional feature, which let me use it myself while I kept iterating on it. Which I did. Now with the upcoming v3 release (targeting next month), I have a well-developed step detection system that I'm going to have on by default, reducing the number of tests that users need to write by ~70%. In some cases, users might not have to write a single test and just be able to pass their Markdown files into Doc Detective as-is. Long story short, the lesson is that you can't rush these things. Play the long game. Give yourself time. As long as you really keep at it, you'll get further than you thought you could. |
Beta Was this translation helpful? Give feedback.
-
|
As someone who has worked extensively with technical documentation, I can say you have a fan of this solution! One of the biggest challenges in documentation is keeping the content up to date and functional. When documenting integrable solutions, we inevitably rely heavily on updates from development and engineering teams, and oftentimes, those responsible for documentation are the last to know about changes. Doc Detective has been incredibly helpful in this continuous improvement process, identifying potential code bugs and enabling Technical Writers to take a more proactive approach with the relevant teams. I was thrilled to see this solution in the spotlight here! |
Beta Was this translation helpful? Give feedback.
-
|
@mecodeatlas I'm so glad you've had success with Doc Detective already! Just wait until v3 releases next month. I have a few tricks up my sleeve that I can hardly wait to show off. |
Beta Was this translation helpful? Give feedback.
-
|
Doc Detective looks really, really interesting. Thank you so much for making such a useful tool like this available to the technical writing and software development communities! You mention you're looking into creating a GUI as well as the CLI tool, but would you also consider an extension/plugin for IDEs like Visual Studio Code, for example? |
Beta Was this translation helpful? Give feedback.
-
|
@dufcrule most definitely! There's a lot we could potentially do with an IDE extension:
The biggest issue right now is contributor bandwidth. If you know someone with a VSCode extension dev who's interested, send them my way! |
Beta Was this translation helpful? Give feedback.
-
|
🕒 Discussion Activity Reminder 🕒 This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions: 1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as 2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own. 3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution. Note: This dormant notification will only apply to Discussions with the Thank you for helping bring this Discussion to a resolution! 💬 |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Meet today’s maintainer, @hawkeyexl from Doc Detective! Doc Detective is an open-source documentation 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.
Read on to learn more about them and their project. We’ll be selecting five people who ask a question to win a $30 GitHub Shop voucher!
What was one of your first contributions to an open source project?
A codebase. I jumped straight into creating and opening up my own project, Doc Detective, instead of starting with contributions to existing projects. I definitely did it the hard way! Since then, I've contributed to multiple documentation-related projects in various capacities. Taking the leap to open source my own work first taught me some hard lessons about project management and community engagement, but the opportunity for growth has been unparalleled.
What do you think every good issue and/or PR should include?
The "why" is critical. For issues, it's important to understand the underlying need rather than just the immediate ask. A feature request might have alternative solutions already available, or there might be better ways to solve the problem that fit better with the project's philosophy.
For PRs, a link to a well-defined issue provides enough of a "why," but in either case, articulating the underlying motivation makes sure that we're solving the real problem in a way that's consistent with the spirit of the project. Understanding the deeper need helps us make informed decisions about implementation approaches and prioritization.
How did you make the decision to become a maintainer of your project, what did you consider?
I feel like I didn't have much of a choice regarding becoming a maintainer. No one had created a tool quite like Doc Detective, which treats documentation as literal assertions of project behavior, transforming docs into repeatable automated tests.
When I created Doc Detective, I saw a gap in the documentation tooling ecosystem. There are lots of tools for performing tests on code—there are very few that can verify documentation accuracy.
Open sourcing it was my way to give back to the documentation community while addressing a real need: helping docs owners keep documentation up-to-date, catching unexpected breaking changes, and giving both users and maintainers confidence in their docs.
The uniqueness of the approach made maintaining it myself a natural decision—it was solving a problem I deeply understood and cared about.
What type of contributions is your project looking for?
We're looking for all types of contributions! Currently, design is our highest priority as we're planning updates to our CLI and working to create a net-new GUI. We also value community management, documentation improvements, and testing contributions.
Code contributions are also always welcome. If you're passionate about creating intuitive interfaces or have ideas about how to make documentation testing more accessible, we'd love your input!
Come join us on our Discord channel!
What is your developer superpower?
Finding unexpected connections—discovering unorthodox ways of combining tools or techniques. My work with Doc Detective is a perfect example: seeing documentation not just as information for humans but as executable assertions. This perspective flips the traditional view of documentation on its head, transforming what many see as a maintenance burden into a powerful testing tool.
By connecting these seemingly separate domains (documentation and testing), we can solve multiple problems simultaneously: improving documentation quality, catching bugs earlier, and reducing maintenance overhead. I'm always looking for these types of non-obvious connections that can lead to elegant solutions for complex problems
Thank you @hawkeyexl, use the comments below to ask him any questions! Asking a question gives you a chance to win a $30 GitHub Shop voucher.
Check out our other Maintainer spotlights
Sweepstakes rules
Beta Was this translation helpful? Give feedback.
All reactions