> The most crucial skill for creating quality documentation is to know your audience This can be tricky when your audience doesn't have a homogeneous skill lev

> The most crucial skill for creating quality documentation is to know your audience This can be tricky when your audience doesn't have a homogeneous skill level (e.g. people copy-pasting GA snippets don't necessarily know JS, and I've even seen seasoned developers disregard the recommendations to put the scripts at specific places in the document and then proceed to wonder why they're sporadically losing tracking data. I've gotten some good feedback from structuring documentation in such a way that a section gradually builds up from the basic knowledge into more domain-specific information [1] The idea is that you can quickly scan `<code>` sections if all you want is to copy-paste blindly or just speed-read code, but you can "zero in" to a section by reading the accompanying paragraph(s). The guide aims to get to the reader's end goal - i.e. "how to use this thing" - by cutting as many details as we can get away with (and then supplementing the nitty-gritty details in the API section). I also have the API section landing page be a cheat sheet, which serves as a quick references and a gateway to drill down into the relevant API section in case the sought information isn't covered by the respective cheatsheet section. I find that it's helpful to have a slightly longer "laundry list" that has some context than just having a shorter dry list of disjointed API method names in a left nav (though I do provide the dry nav as well for the power users). Another thing I find problematic in a lot of docs that I try to address is information architecture. Often times, sites just cobble together a bunch of disjointed sections, which doesn't really help someone who doesn't already know the ins-and-outs of your thing. I try to order the menu items by how advanced are the topics they cover (i.e. tutorials first, followed by more nitty-gritty resources, followed by implementation details). In my opinion, the biggest challenge is to shift mentality from "Oh, I should write about X, and I guess I need to link to it from the menu somewhere" to "what kinds of things would I search for if I was trying to do X/Y/Z, and where would I go to find that information". This exercise can help uncover areas where more linking can help a user understand the relationship between various parts of the system. Another bonus is that it can also help you write more clearly when you have to assume that a user might land in a given section of docs from a link (rather than having the context from the paragraph above). [1](https://mithril.js.org/#getting-started https://mithril.js.org/#getting-started)