On 05 Oct 11:22, Richard Hartmann wrote: > Dear all, > > historically, https://prometheus.io/docs/ has been a reference. > > The plan from early this year was to split docs into sections for > reference, human-readable, and tutorials, and then start filling out > the human-readable version. > > Within Docs WG[1] we realized that we're blocking ourselves. We're > front-loading huge amounts of work which no one of us can > realistically perform in the site setup. On the content side, we carry > huge PRs which are always out of date and a pain to review - without a > public way to find and use them as they're targetting a branch > deploying to an obscure netlify instance, not prometheus.io. > > At the same time, I strongly believe we're doing ourselves and the > wider community a disservice by optimizing for experts instead of new > and intermediate users. > > As such, we would like to propose flipping it around: Optimize docs/ > for new and intermediate users, and do reference at reasonable effort. > This also means that the people volunteering within Docs WG get to > work on what they care about most, and anyone who really wants the > reference can submit a PR to split it out from current HEAD into a > clean structure alongside the human-friendly version.
I do not understand "do reference at reasonable effort". I think that we already do the reference pretty good. Everything that is versionned in the prometheus repo itself is the reference. This is the "expert" documentation, and we do better than a reasonable effort, every new pull request in prometheus should have its documentation in order, so the reference should stay good. I think the "onboarding" documentation should *not* be tied to Prometheus versions and should be managed independently from the Prometheus configuration, in the actual "github.com/prometheus/docs" repository. > > While I am the maintainer of docs/, I would like to get community > consensus on such a change. > > > By sheer coincidence, Dieter, CC'ed, has asked in the Storage WG[2] > call if it would be OK to start putting developer reference directly > into Git. The consensus in that call was "yes". We can always figure > out how to tie this into A Perfect Structure On The Website later. > Starting with a grand plan now and searching for *.md across all our > repos later is better than writing all the docs from scratch once > there's something perfect. > > I think this is 100% uncontroversial, but as it came up in two calls > back-to-back I offered to tack this one onto the text above. > > > Thoughts? > > > Best, > Richard > > [1] > https://docs.google.com/document/d/1k7_Ya7j5HrIgxXghTCj-26CuwPyGdAbHS0uQf0Ir2tw/edit > [2] > https://docs.google.com/document/d/1HWL-NIfog3_pFxUny0kAHeoxd0grnqhCBcHVPZN4y3Y/edit > > -- > 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-developers+unsubscr...@googlegroups.com. > To view this discussion on the web visit > https://groups.google.com/d/msgid/prometheus-developers/CAD77%2BgRxPLjYMFakbhLAZSZgWA-%3DLwKnuCwK1UV2gfz19O9n%3DQ%40mail.gmail.com. -- Julien Pivotto @roidelapluie -- You received this message because you are subscribed to the Google Groups "Prometheus Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to prometheus-users+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/prometheus-users/20211005143110.GA722463%40hydrogen.
