I took a look at documentation.divio.com. Good stuff. I prefer the to group topics by concept, task, and reference, but their model is almost identical but with different words.
A little background on me. I'm a technical writer and have been documenting various things, mostly software, for well over ten years. Developers are experts in coding, I'm an expert in explaining how the software they create works. And Brian's cited documentation system includes a lot that I agree with. For example, the first paragraph in the introduction: > It doesn’t matter how good your product is, because if its documentation > is not good enough, people will not use it. Even if they have to use it > because they have no choice, without good documentation, they won’t use it > effectively or the way you’d like them to. Also in the introduction: > It’s not actually a secret and it certainly shouldn’t be: documentation > needs to include and be structured around its four different functions: > *tutorials*, *how-to guides*, *technical reference* and *explanation*. > Each of them requires a distinct mode of writing. People working with > software need these four different kinds of documentation at different > times, in different circumstances - so software usually needs them all, and > they should all be integrated into your documentation. Here is my professional opinion of the current doc set: What you currently have is NOT good reference documentation. It is inconsistent, wordy, poorly organized, and confusing. Good documentation is clear, consistent, and concise. The Prometheus docs have a looooooong way to go before they get there. You might intend them to be pure reference documents, but they aren't written that way. They're a strange mishmash of how-to information sprinkled in with explanations and abortive attempts at examples. https://documentation.divio.com/ does a good job of modeling active voice, second-person prose, chunking, and other documentation best practices. If that is what you want your docs to be like, then I applaud and encourage it. The good news about the Prometheus docs that you have raw material that can be refined. You just need to figure out what the final version of the docs should look like and make a plan to get there. I agree with your source that you should have a balance of explanations, reference, tutorials, and how-to topics, separated and clear in the function of each. -- You received this message because you are subscribed to the Google Groups "Prometheus Developers" group. To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-developers+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/45aa7e01-4ad4-4d17-af21-2a456e37ff1b%40googlegroups.com.
