On Fri, 17 Apr 2020 at 12:59, Julius Volz <[email protected]> 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 > On Fri, Apr 17, 2020 at 1:19 PM Bjoern Rabenstein <[email protected]> > wrote: > >> 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] [email protected] >> >> -- >> 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/20200417111950.GS2315%40jahnn >> . >> > -- > 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/CA%2BT6Yoxy%2BtSdXFhkeL2bTbveG%3DVjRdOdwFcUpVzkxpariFnJmg%40mail.gmail.com > <https://groups.google.com/d/msgid/prometheus-developers/CA%2BT6Yoxy%2BtSdXFhkeL2bTbveG%3DVjRdOdwFcUpVzkxpariFnJmg%40mail.gmail.com?utm_medium=email&utm_source=footer> > . > -- 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/CAHJKeLq0h5N7t1dUiQsXa0c_-EK3_FrO2-zkQWQ240a0uu3AQg%40mail.gmail.com.
