4 ms·
Meh article but it raises an interesting question: How do you test documentation? The best (and maybe the only real) test is be for someone unfamiliar to try it
by Jeff_Brown 3y ago
Meh article but it raises an interesting question: How do you test documentation? The best (and maybe the only real) test is be for someone unfamiliar to try it and manage to do what it explains. You can't rerun that test without finding a new person.
- schneems 3y agoThat’s legitimately one valid way to test docs. The hard part is finding the target audience. 10 years ago HN was alite with tips like “offer people a $25 gift card to test your X” instead of the current LLM craze. Good design needs feedback. Also I linked in another thread, it’s possible to run and test some types of documentation. It won’t guarantee it is good for the end user but it will at least guarantee it’s doesn’t error.
- macksd 3y agoI always make going through our docs a part of new-hire onboarding. They learn the product, and you learn what in your docs is so confusing that a person who you hired for their supposed ability to help you MAKE your product, can't even figure out ABOUT your product. But also, I did work on a project once where a test would scrape code snippets from documentation and make sure they still worked as expected. It's bad enough to break compatibility in your CLI, etc. but sometimes you need to do it. It's really bad when you have tutorials, recipes, etc. and they bit rot.