I love this idea... it describes (I think) a key point of how Operate
First should actually work.
--Hugh
On Sun, Sep 19, 2021 at 2:01 AM Karsten Wade <kwade(a)redhat.com> wrote:
While we're busy thinking about and working for what our users need, as an open
source project we have to keep an equal attention on the needs of contributors.
Ourselves!
Here's a great idea I learned about, which we started up a few months back:
https://github.com/operate-first/community-handbook
The idea is, everything a contributor needs to know should be in the Operate First
Community Handbook.
If a sought-after part is missing, then it is the responsibility of the original seeker
to bring back what they find out to put in the Community Handbook, as an issue or draft
write-up.
What do you think?
Will you participate as a contributor and user of the Community Handbook?
For this to work, we need all contributors to participate. It is an anti-pattern to have
a small set of people working on the Community Handbook. For it to be effective, it needs
to be the go-to location for all answers, so that handing out a link to the Handbook is
always the best thing to do. (Called "link first culture" in some circles.)
Read on for more details.
Ideally, the Community Handbook is autopublished here:
https://www.operate-first.cloud/community-handbook
Then all of the existing guides in parts of the project, such as the Hitchhiker's
Guide, can be pulled into the Community Handbook automatically. As we have SRE learner
pathways, some of those can be tagged as how-to tutorials auto-included in the Handbook,
and so forth
In fact, we will want to automate a lot of this handbook. For example, imagine a new SRE
contributor who wants to find how something is done. The section in the Community Handbook
automatically pulls in the documentation from the repo as well as the actual runbooks or
other files. When those files are updated in the course of doing work, the Community
Handbook is automatically updated with that information.
The Community Handbook is currently written using the same concept as the rest of the
website, to make it easy to collaborate. We can discuss other tooling methods such as
GitBook or JupyterBook, but we need to be aware of keeping the barrier to writing and
editing the Community Handbook to be as low as possible.
Although a relatively new idea beyond certain projects, you can see a few active examples
here:
https://handbook.chaoss.community/community-handbook/
https://about.gitlab.com/handbook
If this whole thing intrigues you beyond Operate First, you are welcome to join us in the
IEEE SAOpen group where I'm working with some of the folx behind those two handbooks
for defining a toolkit and process anyone can adopt:
https://opensource.ieee.org/community-advisory-group/documentation-curati...
Kind regards,
- Karsten
--
Karsten Wade [he/him/his] | Senior Community Architect | @quaid
Red Hat Open Source Program Office (OSPO) : @redhatopen
The Open Source Way :
https://theopensourceway.org
Operate First :
https://operate-first.cloud
_______________________________________________
Community mailing list -- community(a)lists.operate-first.cloud
To unsubscribe send an email to community-leave(a)lists.operate-first.cloud
--
Hugh Brock, hbrock(a)redhat.com
Research Director, Red Hat
He/him/his
---
"I know that you believe you understand what you think I said, but I'm
not sure you realize that what you heard is not what I meant."
--Robert McCloskey