PS: I forgot to put the references in; https://github.com/prometheus/prometheus/pull/7117 is the trigger for this thread https://groups.google.com/forum/#!searchin/prometheus-users/prometheus$20docs$20richard%7Csort:date/prometheus-users/L1ZLuBnnjDI/uXONrHiOAAAJ is a discussion around _content_, not _structure_
On Wed, Apr 15, 2020 at 2:43 PM 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. > > > As an editorial discussion, I think the user documentation should be > in active voice "you can" and not passive voice "it is possible to". > 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. > We can split out the editorial discussion from this thread if needed. > > > Best, > Richard -- 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%2BgS1YCeic1NR7ZkEH_-V2OQzw8E1%3DjkuZF%2B1mmsLDu8xRw%40mail.gmail.com.
