Added proposal for handbook. #12

bwplotka · 2021-06-02T11:25:52Z

Please review 🤗

Also Preview: https://deploy-preview-12--rhobs-handbook.netlify.app/proposals/accepted/202106-handbook.md/

Signed-off-by: Bartlomiej Plotka bwplotka@gmail.com

bwplotka · 2021-06-02T11:51:27Z

NOTE: Proposal process will be proposed in another PR

jan--f

Love it!

One thing that could be mentioned imho is our user documentation (i.e https://docs.openshift.com/container-platform/4.7/monitoring/understanding-the-monitoring-stack.html). I think we should either explicitly mention it as a non-goal (since I suppose we have processes for that) or mention it as a future item.

dgrisonnet

This is an awesome initiative @bwplotka, thank you for looking into that 🙂

I have a couple of questions that you might be able to ask in regards to that initiative:

How I see one part of the project is as a central place that leverages upstream documentation or any other learning resources and supplements it. One thing that might be hard to understand today is the actual boundary between what should be contributed in the handbook and what should be contributed upstream. Do you think it would be meaningful to document that?
What's the process for upstream enhancements? Should we start drafts in this repository before submitting them to the upstream communities?

content/Proposals/Accepted/202106-handbook.md

dgrisonnet · 2021-06-02T12:33:55Z

content/Proposals/Accepted/202106-handbook.md

+
+### Flow of Adding/Consuming Documentation to Handbook
+
+![flow](../../assets/handbook-proposal.png)


README.md

fpetkovski · 2021-06-02T12:38:17Z

README.md

+This handbook was designed to be used in two ways:
+
+* Through our website `https://rhobs-handbook.netlify.app/`.
+* Directly from GitHub UI by navigating to [`content`](https://github.com/rhobs/handbook/tree/main/content) directory.


What about Github pages?

Do you mean instead of hugo + netlify? We have some amazing pre-processors which makes GitHub UI and website working smoothly (you write docs like for GH UI) (: GH pages would lack of that.

Also we have rdy tooling as other website use it, so we can maintain one way of generating website.

We have some amazing pre-processors which makes GitHub UI and website working smoothly

Interesting, could you send me some links?

https://github.com/bwplotka/mdox/blob/main/main.go#L206

handbook/.mdox.yaml

Line 11 in f1860c7

hugo:

content/Proposals/Accepted/202106-handbook.md

content/contributing.md

kakkoyun

❤️ LGTM

paulfantom · 2021-06-02T13:12:09Z

What's the process for upstream enhancements? Should we start drafts in this repository before submitting them to the upstream communities?

I would vote "upstream first" as docs have this nasty tendency of being stale and not updated or propagated. We can always use links and reference issues/PRs/other pages, no?

paulfantom · 2021-06-02T13:21:46Z

content/Proposals/Accepted/202106-handbook.md

+## Non-Goals
+
+* Support other formats than `Markdown,` e.g. Asciidoc
+* Precise design proposal process (it will come in a separate proposal).


Can we align it with Kubernetes Enhancement Proposal process? This way we would have a sort of test bed for writing KEPs and OEPs :)

Yes, that's the plan, just wanted to keep website and proposals idea separate (although the process will be similar)

Just to mention the tooling behind KEPs is https://github.com/kubernetes-sigs/mdtoc, and they use the following scripts to verify/update the format of each KEP:

https://github.com/thockin/k8s-enhancements/blob/cccc6fa97d5d23e02ad4530d660d306cf49d8c35/hack/update-toc.sh

https://github.com/thockin/k8s-enhancements/blob/cccc6fa97d5d23e02ad4530d660d306cf49d8c35/hack/verify-toc.sh

oh, super useful, will use in next proposal

hm... although it "only" generates TOC, does not verify any format,but cool idea.

bill3tt

I really like that we are aspiring to follow GitLab's examples of open-first documentation ❤️

A shiny new website alone is not going to solve problems we experience when working with documentation.

Let's try it out 💪

README.md

content/Proposals/Accepted/202106-handbook.md

bwplotka

Thanks, everyone for the quick review!

One thing that could be mentioned imho is our user documentation (i.e https://docs.openshift.com/container-platform/4.7/monitoring/understanding-the-monitoring-stack.html). I think we should either explicitly mention it as a non-goal (since I suppose we have processes for that) or mention it as a future item.

Yes good point @jan--f

How I see one part of the project is as a central place that leverages upstream documentation or any other learning resources and supplements it. One thing that might be hard to understand today is the actual boundary between what should be contributed in the handbook and what should be contributed upstream. Do you think it would be meaningful to document that?

I added the handbook-proposal.png with the algorithm to decide. Are there any other rules we can add to make sure it's clearer? (:

What's the process for upstream enhancements? Should we start drafts in this repository before submitting them to the upstream communities?
would vote "upstream first" as docs have this nasty tendency of being stale and not updated or propagated. We can always use links and reference issues/PRs/other pages, no?

Design doc to be added soon in next PR, but the plan is similar to this proposal really. (similar to KEP)

@dgrisonnet

bwplotka · 2021-06-02T13:39:20Z

README.md

+This handbook was designed to be used in two ways:
+
+* Through our website `https://rhobs-handbook.netlify.app/`.
+* Directly from GitHub UI by navigating to [`content`](https://github.com/rhobs/handbook/tree/main/content) directory.


Do you mean instead of hugo + netlify? We have some amazing pre-processors which makes GitHub UI and website working smoothly (you write docs like for GH UI) (: GH pages would lack of that.

Also we have rdy tooling as other website use it, so we can maintain one way of generating website.

content/Proposals/Accepted/202106-handbook.md

bwplotka · 2021-06-02T13:41:53Z

content/Proposals/Accepted/202106-handbook.md

+## Non-Goals
+
+* Support other formats than `Markdown,` e.g. Asciidoc
+* Precise design proposal process (it will come in a separate proposal).


Yes, that's the plan, just wanted to keep website and proposals idea separate (although the process will be similar)

content/Proposals/Accepted/202106-handbook.md

content/contributing.md

README.md

bwplotka · 2021-06-02T16:44:10Z

Thanks I think I addressed all comments, PTAL

Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

content/Proposals/Accepted/202106-handbook.md

Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

bwplotka · 2021-06-03T14:03:52Z

👋🏽 I changed:

Moved naming of this handbook to Monitoring Group to reflect that we have only monitoring team in the process nowhere.
Articulated clearly, that it's not to replace any product documentation - it's mainly for our own documentation to not get lost, have smooth guides and index for further resources.

bwplotka · 2021-06-04T11:51:18Z

If no objection, will merge in couple of hours/Monday. Anyone want to take a look still?

sthaha · 2021-06-07T00:40:34Z

/approve

content/Proposals/Accepted/202106-handbook.md

kyoto · 2021-06-07T07:16:34Z

LGTM

Co-authored-by: Andrew Pickering <andy.nihon@gmail.com>

* Added proposal for handbook. Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com> * Addressed feedback, moved naming to Monitoring Group. Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com> * Update content/Proposals/Accepted/202106-handbook.md Co-authored-by: Andrew Pickering <andy.nihon@gmail.com> Co-authored-by: Andrew Pickering <andy.nihon@gmail.com>

bwplotka force-pushed the proposal2 branch from d411eab to 3ec2c83 Compare June 2, 2021 11:34

jan--f approved these changes Jun 2, 2021

View reviewed changes

dgrisonnet reviewed Jun 2, 2021

View reviewed changes

fpetkovski reviewed Jun 2, 2021

View reviewed changes

kakkoyun approved these changes Jun 2, 2021

View reviewed changes

paulfantom reviewed Jun 2, 2021

View reviewed changes

bill3tt approved these changes Jun 2, 2021

View reviewed changes

README.md Show resolved Hide resolved

content/Proposals/Accepted/202106-handbook.md Outdated Show resolved Hide resolved

bwplotka commented Jun 2, 2021

View reviewed changes

bwplotka force-pushed the proposal2 branch from 3ec2c83 to df2976c Compare June 2, 2021 16:43

Added proposal for handbook.

5feebaf

Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

bwplotka force-pushed the proposal2 branch from df2976c to 5feebaf Compare June 2, 2021 18:11

sthaha reviewed Jun 3, 2021

View reviewed changes

content/Proposals/Accepted/202106-handbook.md Outdated Show resolved Hide resolved

sthaha reviewed Jun 3, 2021

View reviewed changes

content/Proposals/Accepted/202106-handbook.md Outdated Show resolved Hide resolved

Addressed feedback, moved naming to Monitoring Group.

1c63438

Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

fpetkovski approved these changes Jun 4, 2021

View reviewed changes

dgrisonnet approved these changes Jun 4, 2021

View reviewed changes

kyoto reviewed Jun 7, 2021

View reviewed changes

content/Proposals/Accepted/202106-handbook.md Outdated Show resolved Hide resolved

Update content/Proposals/Accepted/202106-handbook.md

c1b82d6

Co-authored-by: Andrew Pickering <andy.nihon@gmail.com>

bwplotka merged commit b3a6f65 into main Jun 7, 2021

bwplotka deleted the proposal2 branch June 7, 2021 11:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added proposal for handbook. #12

Added proposal for handbook. #12

bwplotka commented Jun 2, 2021 •

edited

Loading

bwplotka commented Jun 2, 2021

jan--f left a comment

dgrisonnet left a comment

dgrisonnet Jun 2, 2021

fpetkovski Jun 2, 2021

bwplotka Jun 2, 2021

fpetkovski Jun 2, 2021

bwplotka Jun 2, 2021

kakkoyun left a comment

paulfantom commented Jun 2, 2021

paulfantom Jun 2, 2021 •

edited

Loading

bwplotka Jun 2, 2021

dgrisonnet Jun 2, 2021

bwplotka Jun 2, 2021

bwplotka Jun 2, 2021

bill3tt left a comment

bwplotka left a comment

bwplotka Jun 2, 2021

bwplotka Jun 2, 2021

bwplotka commented Jun 2, 2021

bwplotka commented Jun 3, 2021

bwplotka commented Jun 4, 2021

sthaha commented Jun 7, 2021

kyoto commented Jun 7, 2021


		### Flow of Adding/Consuming Documentation to Handbook

		![flow](../../assets/handbook-proposal.png)

Added proposal for handbook. #12

Added proposal for handbook. #12

Conversation

bwplotka commented Jun 2, 2021 • edited Loading

bwplotka commented Jun 2, 2021

jan--f left a comment

Choose a reason for hiding this comment

dgrisonnet left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kakkoyun left a comment

Choose a reason for hiding this comment

paulfantom commented Jun 2, 2021

paulfantom Jun 2, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bill3tt left a comment

Choose a reason for hiding this comment

bwplotka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bwplotka commented Jun 2, 2021

bwplotka commented Jun 3, 2021

bwplotka commented Jun 4, 2021

sthaha commented Jun 7, 2021

kyoto commented Jun 7, 2021

bwplotka commented Jun 2, 2021 •

edited

Loading

paulfantom Jun 2, 2021 •

edited

Loading