At GitLab our handbook is extensive and keeping it relevant is an important part of everyone's job. The reasons for having our processes described in a handbook are:
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.
Retention is better if people know what they are getting into before they join.
On-boarding is easier if you can find all relevant information spelled out.
Teamwork is easier if you can read how other parts of the company work.
Discussing changes is easier if you can read what the current process is.
Communicating change is easier if you can just point to the diff.
Everyone can contribute to it by proposing a change via a merge request.
A (process) problem comes up, frequently in an issue or chat.
A proposal is made in a merge request to the handbook.
After merging the change is announced by linking to the diff in the MR or commit. Major ones are put in the agenda of the team call. Medium ones are put in a chat channel. If there was an issue close it out with a link to the diff.
Why handbook first
Documenting things in the handbook takes more time initially. You have to think where to make the change, integrate it with the existing content, and possibly add to or refactor the handbook to have a foundation. 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. 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 gist of the change. It might be more convenient to the presenter but it makes it harder for the audience to understand the context and implications for other processes. Handbook first is needed to make sure there is no duplication, the handbook is always up to date, and others are able to contribute.
Please follow these guidelines and remind others of them.
Most guidelines in this handbook are meant to help, and unless stated otherwise, 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, saying for example, "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, and maybe they are proud we have the answer documented. It doesn't mean that you should have read the entire handbook, nobody knows the entire handbook.
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?"
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?"
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?"
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. If 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?"
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.).
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.
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.
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.
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?"
If you copy content please remove it at the origin place and replace it with a link to the new content. Think about the information architecture such that you Don't Repeat Yourself. Duplicate content leads to updating it in the wrong place, keep it DRY.
Make sure to always cross-link items if there are related items (elsewhere in the handbook, in docs, or in issues).
The handbook is structured by function and result to ensure every item in it has a clear owner and location in order to keep it up-to-date. Please cross-link liberally to point people to other sections. Avoid unstructured content based on format like FAQ's, lists of links, resource pages, glossaries, courses, video's, tests, howto's since these are very hard to keep up to date and are not compatible with organization per function and result. Instead put the answer, link, definition, course, video, or test in the most relevant place. Use descriptive headers so that people can easily search for content. Please mix different formats in the handbook on the same page, it is engaging to have multiple formats to use and different people prefer different formats. Worry about the organization per function and result, not about how it will look if you embed a different types of content.
The handbook is the process. Any section sections with names like 'process', 'policies', 'best practices', or 'standard operating procedures' are an indication of a deeper problem, for example duplication between a prose description of a process and a numbered list description of the same process that should be combined in one description of the process.
Use headers liberally. If a page is longer than one screen add an automatically generated Table of Contents (ToC) by copying line 6 to 10 in this MR), on the desktop we have a side bar with the ToC but not on mobile so it is good to add one if there are more than 2 headers. Headers should have normal capitalization (don't use ALL CAPS nor TitleCase). After a header have one blank line, this is not required in the standard but is our convention.
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.
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.
When you submit a merge request, make sure that it gets merged quickly. Making single, small changes quickly will ensure your branch doesn't fall far behind master, creating merge conflicts. Aim to make and merge your update on the same day. 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.
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.
If you have to move content have a merge request that moves it and does nothing else. If you want to clean it up, summarize it, or expand on it do that haver the moving MR is merged. This is much easier to review.
Keep your handbook pages short and succinct. Eliminate fluff and get right to the point with the shortest possible wording. Keep in mind that the biggest challenge cited by new employees is the vast amount of information to take in during on-boarding.
We don't need .gitkeep files in our handbook, they make it harder to quickly open a file in editors. Don't add them, and delete them when you see them.
Anything more than a spelling correction is better done in the terminal than with the online editor. All people that are reluctant to update the handbook are not using the terminal, a local editor, and a local preview. Please follow the instructions in edit this website locally.
When mentioning currency amounts that team members may need to convert to their local currency (e.g. benefits, expenses, or bonuses), link those amounts to our Exchange Rates section (e.g. 500 USD).
It is each department and team member's responsibility to ensure the handbook stays current. People Operations will partner with a representative from each department (engineering, marketing, etc) through weekly reviews to verify the content in the handbook is accurate and follows the same format as outlined in the Guidelines. For questions on who to submit a merge request to, or assistance with the handbook, please ping @gl-handbookupdate on GitLab.
Any changes to the handbook as part of this review will be shared in the #handbook channel in Slack. People Ops will also ensure that questions asked in #questions are documented and all announcements on the team call have a relevant link.
Screenshare the handbook instead of creating a presentation
Another company asked how we managed to work with the handbook because at their company it wasn't working: "There are many occasions where something is documented in the knowledge base, but people don't know about it because they never bothered to read or search. Some people have a strong aversion against what they perceive as a 'wall of text'."
To ensure that people's time is well spend looking at the handbook we should:
Keep your handbook pages short and succinct
Use present tense and simple words
Organize per function so the information architecture is clear
Cross-link liberally so I can find relevant other information easily
Great search function (we use Algolia)
Make it public so you can Google search
Have clean urls and allow for deeplinking paragraphs
Use automatic tables of content
Have lots of headers that give the key message
Make key words bold
When people ask questions link to the handbook instead of giving the answer
Test people on their knowledge during onboarding
Avoid duplication, instead just link
Give real examples
Avoid corporate speak, describe things like you're talking to a friend
Use lots of numbered lists, unordered lists, and tables
Embed video's to consume the content by watching
Add drawings, gifs, cartoons, and graphics to make it interesting and memorable
When someone asks something that isn't there add it to the handbook and respond with a link to the diff