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. 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. 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. > 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/ ? Best, Richard -- 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/CAD77%2BgQ7Y0%3DRsJMwXjZ8KsFxYg8EnABf-G1u699teAj41qf1vw%40mail.gmail.com.
