Handbook Usage
History of the handbook
The handbook started two years after the CHAOSS project was established. We knew that undocumented processes and implicit knowledge were hindering new members from contributing and caused for unnecessary coordination. The handbook was created to capture the roles, responsibilities, and processes within the CHAOSS project and to make this knowledge available to everyone.
At CHAOSS our handbook is new and keeping it relevant is an important part of everyone's job. It is a vital part of who we are and how we communicate. We established these processes because we saw these benefits:
Reading is much faster than listening.
Reading is async, you don't have to interrupt someone or wait for them to become available.
Recruiting is easier if people can see what we stand for and how we operate.
A (process) problem comes up, frequently in an issue or chat.
A proposal is made in a pull request to the handbook.
Once merged, the change is announced by linking to the diff in the pull request or commit. Major ones are put in the agenda of the monthly call. Medium ones are posted on the mailing list for visibility, with a one line summary of the change. If there was an issue, close it out with a link to the diff.
Why handbook first
Documenting in the handbook before taking an action may require more time initially because you have to think about where to make the change, integrate it with the existing content, and then possibly add to or refactor the handbook to have a proper foundation. But, it saves time in the long run, and this communication is essential to our ability to continue scaling and adapting our organization.
This process is not unlike writing tests for your software. Only communicate a (proposed) change via a change to the handbook; don't use a presentation, email, chat message, or another medium to communicate the components of the change. These other forms of communication might be more convenient for the presenter, but they make it harder for the audience to understand the context and the implications for other potentially affected processes.
Having a "handbook first" mentality ensures there is no duplication; the handbook is always up to date, and others are better able to contribute.
Handbook guidelines
Please follow these guidelines and remind others of them.
How we use the guide every day
Most guidelines in this handbook are meant to help, and unless otherwise stated, are meant to help more than being absolute rules. Don't be afraid to do something because you don't know the entire handbook, nobody does. Be gentle when reminding people about these guidelines. For example say, "It is not a problem, but next time please consider the following guideline from the handbook."
If you ask a question and someone answers with a link to the handbook, they do this because they want to help by providing more information. They may also be proud that we have the answer documented. It doesn't mean that you should have read the entire handbook, nobody knows the entire handbook.
How to change or define a process
To change a guideline or process, suggest an edit in the form of a pull request. After it is merged you can talk about it during the weekly call if applicable. You can remind other people of this by asking "Can you please send a pull request for the handbook?"
Communicate process changes by linking to the merged diff (a commit that shows the changes before and after). If you are communicating a change for the purpose of discussion and feedback, it is ok to link to an unmerged diff. Do not change the process first, and then view the documentation as a lower priority task. Planning to do the documentation later inevitably leads to duplicate work communicating the change and it leads to outdated documentation. You can remind other people of this by asking "Can you please update the handbook first?"
Style guide and information architecture
Single Source of Truth Think about the information architecture to eliminate repetition and have a Single Source of Truth (SSoT). Instead of repeating content cross-link it (each text has a hyperlink to the other piece). If you copy content please remove it at the origin place and replace it with a link to the new content. Duplicate content leads to having to update it in multiple changes, which is a lot of work and very easy to forget. If you forget one of the pieces of content is out of date.
Make sure to always cross-link items if there are related items (elsewhere in the handbook, in docs, or in issues).
Scope of this handbook
All documentation that also applies to code contributions from the wider community should be in the GitLab CE project (for example in or the ), not the Handbook, which is only for team members. Read more in the section of the Handbook.
The handbook is for things concerning current and future GitLab team members only. If something concerns users of GitLab, it should be documented in the , the , the or the .
Attribution to GitLab's Handbook
The idea of the handbook originated from . In the spirit of open source, we have copied some passages from GitLab's Handbook.