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? 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.
