On Wed, 15 Apr 2020 at 14:58, 'Diana Payton' via Prometheus Developers < prometheus-developers@googlegroups.com> wrote:
> 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. > That's not an unreasonable assessment. In my opinion this is due to attempts at docs improvement focusing on trying to get our reference docs to do things they aren't suited for, while little work has gone into producing the other types of docs which would let us in the longer term clean up the various non-reference material that currently lives in the reference docs. Brian > 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 > <https://groups.google.com/d/msgid/prometheus-developers/45aa7e01-4ad4-4d17-af21-2a456e37ff1b%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- Brian Brazil www.robustperception.io -- 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/CAHJKeLqNWtOZ66tk%3D5miqomdhWuYbenSC1u59ujhNZf_yj044g%40mail.gmail.com.
