4 ms·
Insanely effective tip: watch a junior dev use your docs, offer no assistance, and have them say out loud what they're thinking and doing. You'll discover dozen
by nomilk 4y ago
Insanely effective tip: watch a junior dev use your docs, offer no assistance, and have them say out loud what they're thinking and doing. You'll discover dozens of ambiguities, 'gotchas', and shortcomings!
It's important to use a new junior each time (i.e. if they've used your docs before, don't use that person again). They should also try to accomplish a real task (not just proofreading the docs, but actually using the docs for their intended purpose).
I've used docs from Salesforce and Google and can tell they haven't been tested in this way since they contain (glaring) problems that would easily be found and addressed in a few minutes.
I use this approach often, and gain enormously from it.
- Master_Odin 4y agoHaving used a handful of dev nodejs Google docs in the past few weeks, at this point I can only assume that aggressively hate the devs trying to consume their stuff. Their docs (and examples, and TS types) are often out of date, missing details (eg missing docs on accepted parameters or even whole functions), and just require more codebase reading across multiple libraries to deduce usage.
- nicbou 4y agoThis is how I wrote our company documentation. I'd watch new employees struggle and use that to improve things. My first pull request at a company was usually a README update. Now I write documentation for a living, and I still do the same. It's just a lot harder to tail my readers.
- specialist 4y agoYup. Ages ago, I transitioned from UI to tech writing. I usability tested all of our docs, pretty much as you describe. Thereafter, my products received very few tech support calls.