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:
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:
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:
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:
Kind regards,
- Karsten
--