I tend to agree with Brian, I don’t think we should change our existing structure but I’m all for adding more user guide style docs.
No strong opinion on the wording. On Wed 15. Apr 2020 at 14:53, Brian Brazil <[email protected]> wrote: > On Wed, 15 Apr 2020 at 13:44, Richard Hartmann < > [email protected]> wrote: > >> Dear all, >> >> currently our documentation is treated largely treated as reference >> documentation, i.e. useful to look up stuff you already know or at >> least fundamentally understand. We have a few guides, which do not >> tell a consistent story of "I have nothing, and I want to have >> something" i.e. "Hello World!" yet. >> >> Reviving a discussion from 2016-ish, I would like to propose that we >> use our current reference docs as the starting point for actual user >> documentation and move the reference to a space in which it can >> continue for looking up stuff people already know and understand. >> >> Structure in `docs/` should be retained as far as possible so as not >> to break incoming links, I suggest copying the same structure and >> content under `docs/reference/`, and then starting to edit `docs/` to >> be useful to newcomers. >> > > 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. > > 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. > > >> As an editorial discussion, I think the user documentation should be >> in active voice "you can" and not passive voice "it is possible to". >> > > When you say user documentation, which type of docs are you talking about? > > In terms of types of documentation https://documentation.divio.com/ > matches my personal experiences. > > >> The current reference documentation is inconsistent, I don't know if >> anyone would care to clean it up into completely active or completely >> passive voice. >> > > 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. > > Brian > > >> We can split out the editorial discussion from this thread if needed. >> >> >> 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%2BgTMqNA4uR-yedUYeWea6ZDc_PWCBQZJEFuFb%2BioAsdmpQ%40mail.gmail.com >> . >> > > > -- > 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/CAHJKeLoaLp1fovYXw3g6gNapCJieRgtMUtjuC6O-zuerLU50hg%40mail.gmail.com > <https://groups.google.com/d/msgid/prometheus-developers/CAHJKeLoaLp1fovYXw3g6gNapCJieRgtMUtjuC6O-zuerLU50hg%40mail.gmail.com?utm_medium=email&utm_source=footer> > . > -- 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/CAOs1UmzfAyixD7yo8kfWJWf-aDSY5s%3DBy32Zk4u_9jqxk1KLCQ%40mail.gmail.com.
