[oggy]

Great comment about missing the forest from the trees. The course outline reminds me of an article on "writing great code" that lists the rules of a code formatter.

My personal tips for writing docs: 1. think about what you need to get across and to whom. I've found this categorization helpful (just don't get religious about it): https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o... 2. try to say whatever you're saying with as few words as possible. "Vigorous writing is concise" is probably the best takeaway I got from Strunk & White (not a huge fan of the book otherwise) 3. do a few passes. "Keep rewriting" is probably the best takeaway I got from "On Writing Well" (but I like that book in general).

[205guy]

The trick to writing that works for me is to combine tips 2 and 3 iteratively. I don’t write concisely at first (and I think that’s the case for most people), so I just write down everything I can think of related to the topic, even all the edge cases. Then I go back and simplify, maybe focus on a relevant example. I cut out fluff and stick to that example, perhaps with the list of edge cases in a separate section (and call it “Advanced Use Cases”).