[lhorie]

I think of documentation as my little secret superpower. It makes one more productive (i.e. one doesn't need to keep getting interrupted to be asked the same question yet again), it makes others more productive (they can unblock themselves and use the docs to supplement their little corner of tribal knowledge), and good docs allows one to offload knowledge of specifics from one's brain such that just searching for a keyword is sufficient to recall all the nitty-gritty context one needs to fix whatever is the issue at hand.

My general approach is: if a question gets answered in chat, also add it to docs. Personally I dump each question as a markdown header + paragraphs (typically with an error message or uniquely identifiable string in the header), using a FAQ format under whichever page makes the most sense. Then it's easy to find the section w/ the search widget (we use js-search on a next.js SSG site) and it's easy to link to the specific header. Then, the next time the question gets posted on chat, just open docs, search, copy permalink, paste, done.

I agree that making full-fledged, truly useful docs is a lot of work, but you'd also be surprised how much you can get out of relatively little work.

[porker]

What's your superpower to write documentation that helps others? Too often I find I'm writing docs for myself and they confuse users.

Do you have a set of questions you ask yourself when writing, to check it will be useful and usable by users?

[lhorie]

Some people like to point to this resource[0]

At the end of the day, it comes down to identifying what kind of audience is reading.

The ideal (and hard) way to go about docs is to be redundant/verbose/overcommunicative to target different audiences with different forms of writing.

The paretto approach is to laser focus on the one type of docs that help the most. My super dumb heuristic for this is just looking at question frequency in chat and offering the FAQ that would've answered the question.

What I sometimes try to do is link from an FAQ to a more elaborate section if there's rationales to be explained. Then the skimmer can quickly copy-paste, and the digger can go optionally read more in-depth content.

Our docs are also loosely structured by order-of-learning (e.g. "what is X", "here's pages about the most important components of X" and how they typically tie together, each page with their own FAQs, and then finally an API reference)

For mithril.js[1], I have intro ("tell me what this is and why should I care"), tutorial ("going from zero to hero"), guides ("how to setup specific things"), API reference ("what methods exist"). There's also a glossary ("what does the lingo mean") and a cheatsheet ("just let me copy and paste").

[0] https://documentation.divio.com/

[1] https://mithril.js.org/

[majkinetor]

I have similar approach. If I can't send you think link on Slack, its not good enough. If you don't understand, I update the docs and send you the link/diff again.