Structure of reference and user documentation

[Richard Hartmann]

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 Hartmann]

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_

--
Richard

[Brian Brazil]

On Wed, 15 Apr 2020 at 13:44, Richard Hartmann <richih.ma...@gmail.com> 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 prometheus-devel...@googlegroups.com.
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

[Frederic Branczyk]

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.

To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/CAHJKeLoaLp1fovYXw3g6gNapCJieRgtMUtjuC6O-zuerLU50hg%40mail.gmail.com.

[Richard Hartmann]

On Wed, Apr 15, 2020 at 2:53 PM Brian Brazil
<brian....@robustperception.io> 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

[Diana Payton]

I took a look at documentation.divio.com. Good stuff. I prefer the to group topics by concept, task, and reference, but their model is almost identical but with different words.

A little background on me. I'm a technical writer and have been documenting various things, mostly software, for well over ten years. Developers are experts in coding, I'm an expert in explaining how the software they create works.

And Brian's cited documentation system includes a lot that I agree with. For example, the first paragraph in the introduction:

It doesn’t matter how good your product is, because if its documentation is not good enough, people will not use it. Even if they have to use it because they have no choice, without good documentation, they won’t use it effectively or the way you’d like them to.

 Also in the introduction:

It’s not actually a secret and it certainly shouldn’t be: documentation needs to include and be structured around its four different functions: tutorials, how-to guides, technical reference and explanation. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all, and they should all be integrated into your documentation.

Here is my professional opinion of the current doc set: What you currently have is NOT good reference documentation. It is inconsistent, wordy, poorly organized, and confusing. Good documentation is clear, consistent, and concise. The Prometheus docs have a looooooong way to go before they get there.

You might intend them to be pure reference documents, but they aren't written that way. They're a strange mishmash of how-to information sprinkled in with explanations and abortive attempts at examples.

https://documentation.divio.com/ does a good job of modeling active voice, second-person prose, chunking, and other documentation best practices. If that is what you want your docs to be like, then I applaud and encourage it.

The good news about the Prometheus docs that you have raw material that can be refined. You just need to figure out what the final version of the docs should look like and make a plan to get there. I agree with your source that you should have a balance of explanations, reference, tutorials, and how-to topics, separated and clear in the function of each.

[Brian Brazil]

On Wed, 15 Apr 2020 at 14:58, 'Diana Payton' via Prometheus Developers <prometheus...@googlegroups.com> wrote:

I took a look at documentation.divio.com. Good stuff. I prefer the to group topics by concept, task, and reference, but their model is almost identical but with different words.

A little background on me. I'm a technical writer and have been documenting various things, mostly software, for well over ten years. Developers are experts in coding, I'm an expert in explaining how the software they create works.

And Brian's cited documentation system includes a lot that I agree with. For example, the first paragraph in the introduction:

It doesn’t matter how good your product is, because if its documentation is not good enough, people will not use it. Even if they have to use it because they have no choice, without good documentation, they won’t use it effectively or the way you’d like them to.

 Also in the introduction:

It’s not actually a secret and it certainly shouldn’t be: documentation needs to include and be structured around its four different functions: tutorials, how-to guides, technical reference and explanation. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all, and they should all be integrated into your documentation.

Here is my professional opinion of the current doc set: What you currently have is NOT good reference documentation. It is inconsistent, wordy, poorly organized, and confusing. Good documentation is clear, consistent, and concise. The Prometheus docs have a looooooong way to go before they get there.

You might intend them to be pure reference documents, but they aren't written that way. They're a strange mishmash of how-to information sprinkled in with explanations and abortive attempts at examples.

That's not an unreasonable assessment. In my opinion this is due to attempts at docs improvement focusing on trying to get our reference docs to do things they aren't suited for, while little work has gone into producing the other types of docs which would let us in the longer term clean up the various non-reference material that currently lives in the reference docs.

Brian

https://documentation.divio.com/ does a good job of modeling active voice, second-person prose, chunking, and other documentation best practices. If that is what you want your docs to be like, then I applaud and encourage it.

The good news about the Prometheus docs that you have raw material that can be refined. You just need to figure out what the final version of the docs should look like and make a plan to get there. I agree with your source that you should have a balance of explanations, reference, tutorials, and how-to topics, separated and clear in the function of each.

--

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 prometheus-devel...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/45aa7e01-4ad4-4d17-af21-2a456e37ff1b%40googlegroups.com.

--

Brian Brazil

www.robustperception.io

[Brian Brazil]

On Wed, 15 Apr 2020 at 14:49, Richard Hartmann <richih.ma...@gmail.com> wrote:

On Wed, Apr 15, 2020 at 2:53 PM Brian Brazil
<brian....@robustperception.io> 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

[Bjoern Rabenstein]

On 15.04.20 14:50, Richard Hartmann wrote:
>
> 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_

Then I have to apologize that I added a lot of structural aspects to
the latter discussion. However, now that I have done it, the disussion
there _is_ also about structure. I won't repeat my ideas from that
thread here. They were essentially a dump of notes I took over time
about quite concrete aspects.

I'm lacking capacity at the moment to take part in the details, but I,
too, think the docs are in desperate need of improvement, and I really
appreciate that things get rolling again now. In particular, it's
great that Diana can help us as a professional tech writer.

Without going into details, as said, I just want to share some
high-level ideas and observations from a bit of distance:

First of all, the discussion appears more controversial than it
actually is or could be. There seems to be a broad consensus about the
most important aspects:

- There are different kinds of documentation, and while they are all
necessary, they need to be clearly separated. Trying to cater for
the different needs with the same piece of documentation is doomed
to fail.

- The current doc site is mostly reference style, but even as that, it
needs a lot of improvement.

- Awesome resources have been linked in the thread, and they seem to
be universally accepted as good guidelines.

My ideas/suggestions:

- I think as the very first thing, we should agree on a
styleguide. Personally, I don't feel strongly how it exactly looks
like, but I do feel strongly that we need one (and that's probably
true for most of us). It just doesn't make sense to discuss active
vs. passive voice or 2nd vs. 3rd person in a PR that's supposed to
merele straighten up some details. Ideally, we could get behind an
existing styleguide we can then simply link (similar to what we did
with the Go coding styleguide), but I leave that to those who feel
more strongly about the style.

- I believe our doc site should aim to satisfy all consumers of docs,
but the different types of docs need to be clearly separated within
the site. I don't like statements like "prometheus.io is mostly
reference documentation, go elsewhere if you need something else".

- I believe the structure of the documentation is very important. I
don't buy that we can first create content and then think about how
to structure it. One will inform the other, so both have to develop
along with each other. Similar to the styleguide, I think it makes
sense to have a "master plan" for the structure. While creating a
good flow through the site for beginners is both harder and more
important than for the experts, I don't believe one has to come at
the expense of the other. A well planned structure will improve the
flow for all groups and dissolve that false dichotomy.

Richi made a concrete suggeston to copy the existing docs into a
/reference directory and then evolve both copies differently into the
different types of documentation. Personally, I don't think that's a
good strategy. I also don't think that it helps keeping existing links
working. Existing links are more likely meant to be into the reference
docs. From that perspective, it's probably better to create new path
patterns for the more dearly missing kinds of documentation and keep
the most "referency" parts, in particular
https://prometheus.io/docs/prometheus/..., which is coming from the
prometheus/prometheus repo directly and supports versioned links. In
different news, I don't even think keeping existing links working is a
top priority. It shouldn't slow down improvements in the structure of
the site. However, I'm now getting lost in details, which wasn't my
intention. Looping back to the "structure master plan": Once there is
a common goal, it's not that problematic anymore which detailed path
we take to get there.

--
Björn Rabenstein
[PGP-ID] 0x851C3DA17D748D03
[email] bjo...@rabenste.in

[Julius Volz]

Agreed with everything that Björn said. Great that we actually all agree on more than the controversial tone here could have suggested.

Question is, does someone feel called upon (and has the capacity) to coordinate such a style guide and structural master plan?

--
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 prometheus-devel...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/20200417111950.GS2315%40jahnn.

[Brian Brazil]

On Fri, 17 Apr 2020 at 12:59, Julius Volz <juliu...@gmail.com> wrote:

Agreed with everything that Björn said. Great that we actually all agree on more than the controversial tone here could have suggested.

I'm also largely in agreement with Björn.

 

Question is, does someone feel called upon (and has the capacity) to coordinate such a style guide and structural master plan?

Over the years there's been various talks and plans about the docs, but the actual output in terms of documentation has been low - basically just the Guides section which is going in the right direction but not as broad as one would hope. Thus I'm a bit dubious that spending time on more planning is likely to be fruitful, but trying to develop e.g. a PromQL tutorial might get us somewhere.

Brian

To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-developers/CA%2BT6Yoxy%2BtSdXFhkeL2bTbveG%3DVjRdOdwFcUpVzkxpariFnJmg%40mail.gmail.com.

--

Brian Brazil

www.robustperception.io

[Diana Payton]

Question is, does someone feel called upon (and has the capacity) to coordinate such a style guide and structural master plan?

I would recommend starting with a documentation analysis and inventory. Figure out what you have and what is going on with your current doc set. Trust me, you will learn a lot from this process. This is just a documentarian truism.

You can't really plan until you have a clear picture of the current state.

Steps after that would be decide on a style guide (informed by notes made during the analysis) and create a plan with priorities (based on what you learn from the inventory).

Diana 

[Julius Volz]

That all sounds great to me! Would you be interested in leading this? I'd be happy to help with going through everything, providing context, and pointing out challenges we have (like versioned docs for the different ecosystem components, etc.).