Change the focus of our docs section
15 views
Skip to first unread message
Richard Hartmann
Oct 5, 2021, 5:22:25 AM10/5/21
to Prometheus Developers, Prometheus Users, Dieter Plaetinck
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.
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
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.
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
Julien Pivotto
Oct 5, 2021, 10:34:28 AM10/5/21
to Richard Hartmann, Prometheus Developers, Prometheus Users, Dieter Plaetinck
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".
> 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 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-devel...@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
Bjoern Rabenstein
Oct 7, 2021, 7:09:11 AM10/7/21
to Richard Hartmann, Prometheus Developers, Prometheus Users, Dieter Plaetinck
On 05.10.21 11:22, Richard Hartmann wrote:
>
> 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.
> [...]
>
> 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.
> As such, we would like to propose flipping it around: Optimize docs/
> for new and intermediate users, and do reference at reasonable effort.
I appreciate a clean and concise reference documentation.
> for new and intermediate users, and do reference at reasonable effort.
But if keeping it perfectly clean is the enemy of some good
incremental doc improvements, I don't mind being less strict about it.
I trust the Docs WG to find the right balance here.
--
Björn Rabenstein
[PGP-ID] 0x851C3DA17D748D03
[email] bjo...@rabenste.in
Chris Sinjakli
Oct 10, 2021, 8:00:56 PM10/10/21
to Bjoern Rabenstein, Richard Hartmann, Prometheus Developers, Prometheus Users, Dieter Plaetinck
> 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.
> Prometheus versions and should be managed independently from the
> Prometheus configuration, in the actual "github.com/prometheus/docs"
> repository.
Agree with keeping evergreen documentation outside of the release cycle
of Prometheus itself. I think that the cases where you want to refer to
something version-specific in that style of documentation will be the
exception rather than the rule, and can be handled with a temporary
"This is available from Prometheus version X" notice.
I'm not sure if it's helpful in terms of clarifying different styles of
docs that might be worth focusing on, but a coworker at my last job
introduced me to this framing of different types of docs:
https://documentation.divio.com/
which I found quite useful.
I think there's still huge value in having reference docs, but of all
the styles they're the most useful when you already know and understand
most of what you're doing, and just need to look at details for a few
specific features.
of Prometheus itself. I think that the cases where you want to refer to
something version-specific in that style of documentation will be the
exception rather than the rule, and can be handled with a temporary
"This is available from Prometheus version X" notice.
I'm not sure if it's helpful in terms of clarifying different styles of
docs that might be worth focusing on, but a coworker at my last job
introduced me to this framing of different types of docs:
https://documentation.divio.com/
which I found quite useful.
I think there's still huge value in having reference docs, but of all
the styles they're the most useful when you already know and understand
most of what you're doing, and just need to look at details for a few
specific features.
Reply all
Reply to author
Forward
0 new messages