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