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.
