GitLab Handbook Usage

At GitLab our handbook is extensive and keeping it relevant is an important part of everyone's job. The reasons for having a handbook are:

  1. Reading is much faster than listening.
  2. Reading is async, you don't have to interrupt someone or wait for them to become available.
  3. Recruiting is easier if people can see what we stand for and how we operate.
  4. Retention is better if people know what they are getting into before they join.
  5. Onboarding is easier if you can find all relevant information spelled out.
  6. Teamwork is easier if you can read how other parts of the company work.
  7. Discussing changes is easier if you can read what the current process is.
  8. Communicating change is easier if you can just point to a diff.
  9. Everyone can contribute to it by proposing a change via a merge request.

Documenting things in the handbook takes more time initially and it requires thinking. But it saves time over a longer period and it is essential to scale and adapt our organization. It is not unlike writing tests for your software. Please follow these guidelines and remind others of them.

  1. If you need to discuss with a team member for help please realize that probably the majority of the community also doesn't know, be sure to document the answer to radiate this information to the whole community. After the question is answered, discuss where it should be documented and who will do it. You can remind other people of this by asking "Who will document this?"
  2. When you discuss something in chat always try to link to a URL where relevant, for example, the documentation you have a question about or the page that answered your question. You can remind other people of this by asking "Can you please link?"
  3. To change a guideline or process, suggest an edit in the form of a merge request. After it is merged you can talk about it during the team call if applicable. You can remind other people of this by asking "Can you please send a merge request for the handbook?"
  4. Communicate process changes by linking to the diff (a commit that shows the changes before and after). 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 to outdated documentation. You can remind other people of this by asking "Can you please update the handbook first?"
  5. Remember, the handbook is not what we hope to do, what we should formally do, or what we did months ago. It is what we do right now. So if you want to change a process change the handbook in order to change it. To propose a change to a process make a merge request to change the handbook. Don't use another channel to propose a handbook change (email, Google Doc, etc.).
  6. Like everything else, our processes are always in flux. Everything is always in draft, the initial version should be in the handbook, too. If you are proposing a change to the handbook, whenever possible, skip the issue and submit a merge request. Mention the people that affected by the change in the merge request. In many cases, merge requests are easier to collaborate on since you can see the proposed changes.
  7. To propose a change a merge request is preferred over an issue description. A merge request allows people to see the context of your change.
  8. If something is a limited test to a group of users, add it to the handbook and note as such. Then remove the note once the test is over and every case should use the new process.
  9. When communicating something always include a link to the relevant (and up to date) part of the handbook instead of including the text in the email/chat/etc. You can remind other people of this by asking "Can you please link to the relevant part of the handbook?"
  10. 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 updating it in the wrong place, keep it DRY.
  11. Make sure to always cross-link items if there are related items (elsewhere in the handbook, in docs, or in issues).
  12. The handbook is structured by function to ensure every item in it has a clear owner and location. Please cross-link liberally but avoid unstructured content like lists of links, FAQ's, and company wide glossary since these are very hard to keep up to date. Instead put the link, the answer, and the definition in the most relevant place.
  13. Use headers liberally. Add a Table of Contents (ToC) if a page is longer than one screen. Headers should have normal capitalization (don't use ALL CAPS nor TitleCase).
  14. If someone inside or outside GitLab makes a good suggestion invite them to add it to the handbook. Send the person the url of the relevant page and section and offer to do it for them if they can't. Having them make and send it will make the change and review reflect their knowledge.
  15. All documentation that also applies to code contributions from the wider community should be in the GitLab CE project (for example in CONTRIBUTING or the code review guidelines, not the handbook that is only for team members.
  16. Learn how to edit the handbook using git. Please read through the Writing Style Guidelines before contributing.
  17. When you submit a merge request, make sure that it gets merged quickly. It should not take more than a few days to get a merge request approved to the handbook. Mention people in the merge request or reach them via Slack. If you get a suggestion for a large improvement on top of the exiting one consider doing that separately. Create an issue, get the exiting MR merged, then create a new merge request. Getting your merge requests approved quickly may prevent merge conflicts from happening.
  18. Only mark a merge request as "WIP" (Work in Progress) if it will negatively affect the company if merged too early. That can be the case for application code but is almost not possible for handbook MRs.
  19. The handbook is for things concerning (future) GitLab team members only. If something concerns users of GitLab, it should be documented in the GitLab documentation, the GitLab Development Kit (GDK), the CONTRIBUTING file or the PROCESS file.