On Wed, 15 Apr 2020 at 14:49, Richard Hartmann <[email protected]> wrote:
> On Wed, Apr 15, 2020 at 2:53 PM Brian Brazil > <[email protected]> wrote: > > > I am against breaking existing users depending on where our reference > docs are. I'm also against duplicating our existing reference docs as > reference docs are not a good base for other types of documentation, and > it'd likely lead to outdated documentation. > > That stance is well-understood. To re-iterate my stance: The reference > is useful for people who know what they're doing. Guides are useful > for following along a pre-determined path of learning. > I agree. > Our reference docs are largely lacking in the lower left quadrant of > https://documentation.divio.com/ - they do not explain concepts. > > I would argue that the most important type of documentation is > precisely the "explain concepts and how at the same time". Guides tend > to have too much fluff, references are useless for learning unless you > already have context. > What's most important varies depending on what your current goal is. New users probably want tutorials and how-tos, experienced users more explanations and references. I don't know how often I have had conversations where users told me > how useless our current docs are, but I know I agreed with them every > time. > > > As additions to the "reference docs" are nipped in the bud, I want to > a) get, or document, wider consensus on the direction of `docs/` > b) keep the reference accessible for advanced users, but move it out > of the immediate discovery path of newcomers > > > > If someone wishes to add tutorials there's an existing Guides section, > and I'd prefer those looking to expand the docs start there rather trying > to make reference docs do things that reference docs aren't suited to. > > That is precisely why I am pulling this discussion into a wider base. > You know my stance. I know your stance. Neither of us can say for > certain what the wider consensus is. > > > To quote https://documentation.divio.com/reference/ > For some developers, reference guides are the only kind of > documentation they can imagine. They already understand their > software, they know how to use it. All they can imagine that other > people might need is technical information about it. > I am not one of those developers. Over the years we've managed to keep our reference docs largely complete and correct, and I don't think that's something we should be losing. That isn't to say that I think it's the only type of doc we should have, and indeed we have a mix of the doc types currently (with a less than optimal organisation). The problem is that we largely haven't had contributions of the other types of docs, e.g. we don't have a PromQL tutorial. > > > Reference documentation is about describing a piece of software, so we > should be talking about the software in the 3rd person rather than talking > to the user in the 2nd person. "it is possible to" would be unclear for > reference documentation, I don't want to know some things that might be > possible - I want to know exactly how the software behaves. > > Would you be interested in cleaning up the inconsistencies of the > reference; ideally once it has been split according to the matrix on > https://documentation.divio.com/ ? > I think the first thing to do would be to have more content, then we can figure out how it is best laid out. For example I see no point in talking about not pointing new users at the PromQL reference docs until we have something better to point them to, otherwise we're just making it harder to find the docs we do have. I'm also not a fan of making things harder to find for users who do actually want the reference docs. -- 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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/CAHJKeLpKhXAsUBOi%2Bsn2J-A-sn5gj2M5jF-OrRGpaYsSqv%3D0iw%40mail.gmail.com.
