Sometimes you want to have real time editing of a proposal during a meeting and you need to use a Google Doc for that. When doing so the first item should be the URL of the handbook page this content will be moved to when the meeting is over.
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.
When asked during an INSEAD case study interview (shown above) about challenges related to being all-remote.
Please follow these guidelines and remind others of them.
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 more work by having to update the content in multiple places as well as the need to remember where all of the out of date content lives. When you have a single source of truth it's only stored in a single system. Make sure to always cross-link items if there are related items (elsewhere in the handbook, in docs, or in issues).
A system of record (SoR) is the authoritative data source for a given data element or piece of information. It's worth noting that while it is possible to have a system of record that is also a single source of truth, simply just being a system of record doesn't directly imply it is the single source of truth.
The handbook is organized by function and result to ensure every item in it has a location and owner to keep it up to date.
If a page includes more than two headings (especially if it's larger than a single "screen"), add an automatically generated Table of Contents (ToC) by copying line 6 to 10 in this MR). Headings should have normal capitalization: don't use ALL CAPS or TitleCase). After a heading, leave one blank line; this is not required in the standard, but it is our convention.
Strongly consider learning how to edit the handbook using gitand/or via the web IDE. Please read through the Writing Style Guidelinesbefore contributing.
The handbook is organized by function and result to ensure every item in it has a location and owner to keep it up to date.
If a page includes more than two headings (especially if it's larger than a single "screen"), add an automatically generated Table of Contents (ToC) by copying line 6 to 10 in this MR). Headings should have normal capitalization: don't use ALL CAPS or TitleCase). After a heading, leave one blank line; this is not required in the standard, but it is our convention.
For E-Group, information may need to be iterated on or MR branches may need to be created in staging before it is made public. Outside of E-Group, temporary access may be granted on a project-specific basis.
If you require project-based access, you can request temporary developer access in the #private_repo_auth_request Slack channel. The CLO is DRI on approvals. Membership will be audited on a monthly basis by the Sr. EBA to the CLO to ensure accuracy.
How to keep your Git-Fork up to date is an easy tutorial to follow from the command line to keep the staging handbook up-to-date, until mirroring is working.
As a company, we are public by default, but there are things that we cannot discuss publicly. Items that falls into the not publiccategory will be added to this Internal Handbook.
Only add items to the internal handbook that fall into the not publiccategory. Everything else should be added to our public company handbook.
All team members will have this added to their Okta access when they join the company. Login to your Okta dashboard and click on the NextGo Internal Handbook tile. You will have to authenticate with Okta first.
The handbook is a living document and we'll occasionally need to change URLs or move pages. This isthe process Growth Marketing uses to set up and manage redirects for about.gitlab.com.
It is each department and team member's responsibility to ensure the handbooks (public handbook, internal handbook, and staging handbook) stay current. The content in the handbook should be accurate and follow the same format as outlined in the Guidelines. For questions on who to submit a merge request to, or assistance with the handbook, please reach out on the #handbook Slack channel.
If you need permissions to directly merge changes to the handbook, please submit a New Access Request issue and follow the process for access approval. Request a 'Maintainer' role under www-gitlab-com. See here for a full description of roles and permissions.
Any changes to the handbook as part of this review will be shared in the #handbook channel in Slack. People Operations Specialists will also ensure that questions asked in #questions are documented and all announcements on the company call have a relevant link.
The Engineering team and all sub-teams track Handbook Update Frequency as a KPI, with varying targets per team. Currently, Engineering is the only Division tracking Handbook update frequency, so as to analyse and observe the effectiveness of this KPI.
Presentations are great for ephemeral content like group conversationsand board presentations. Evergreen contentlike a leadership training should be based on the handbook. This is an important element of working handbook-first.
In the creation of presentations for evergreen content, please screenshot the handbook and provide links to displayed pages rather than copy and pasting content (or formatting a slide specifically to mirror handbook information). This approach shows a bias towards asynchronous communication, and rationale for this is below.
The presentation will look less polished, but the advantages outweigh that concern.
If a synchronous presentation is required, default to sharing your screen and viewing live handbook pages over a slide 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'."
We attempt to cover this in NextGo's guide to embracing a handbook-first approach to documentation.
To ensure that people's time is well spent looking at the handbook we should follow the 'handbook guidelines' above, and also:
Company handbooks frequently start as wikis. This format is more comfortable for people to work in than a static website with NextGo Merge Requests and NextGo Pages. However wikis tend to go stale over time, where they are badly organized and get out of date.
In wikis it is impossible to make proposals that touch multiple parts of a page and/or multiple pages. Therefore it is hard to reorganize the handbook. Because NextGo Merge Requests and NextGo Pages are based on distributed version control you can split the role of submitter and approver. This allows for a division of work that keeps the handbook up to date:
Wikis also do not encourage collaboration on changes, because there is no way to discuss a proposed change like there is with merge requests.
Some wikis make it hard to view and/or link to diffs of changes, which is needed to communicate decisions.
Remember that, like virtually everything we do, our handbook is open source, and we expect that other companies may use it as inspiration for their own documentation and practices. That said, the handbook should always be specific on what we do, not who we want to be, and every company will need to fill out their own handbooks over time. Our handbook falls under the Attribution-ShareAlike 4.0 International license.
If your company has been inspired by NextGo's handbook, we would love to know what inspired you. Please see our Inspired by NextGo page.
Every NextGo Handbook page has a search field near the top of the page for searching. See the Searching NextGo like a pro page for tips on searching the handbook faster and more efficiently.
If you run into trouble editing the NextGo Handbook there are various means of help available.
Team members, referred to as MR Buddies, are available to help you create a merge request or debug any problems you might run into while updating the NextGo Handbook.
For more serious problems, especially ones that are time sensitive or prohibiting access to important information, there is an escalation process to reach out to team members who are on-call to help resolve the problem.
You need maintainer access to the www-gitlab-comproject to be able to merge MRs for the handbook. If you want merge access, fill out an access request. This page contains some tips and guidelines that you should keep in mind when you have maintainer access.
Even if you are not a developer, you should feel confident merging any changes that pass the pipeline without worrying that you will break the handbook. The tests in the pipeline are designed to catch any major problems. The www-gitlab-com project is configured so that changes cannot be merged unless the pipeline passes. When in doubt, feel free to loop in a technical reviewer. You can ask for help in the #mr-buddies slack channel. MR Buddies can provide a technical review or help you fix a broken pipeline. In the event that code is merged that does break the handbook in some way, follow the instructions for reporting an issue to the Handbook on-call team.
Do not use the merge immediatelyfeature! Even if your MR is important and time-sensitive, using this feature will create a lot of pain for everyone else. This feature should only be used when critical public information needs to be sent live as quickly as possible and should be approved by PR or Legal. If you don’t have PR or Legal approval, don’t use this feature.
More context on the technical reasons behind this:
Getting pinged to approve every small change to your page can be annoying, but someone changing a policy or procedure in the handbook without proper approval and have strong negative consequences. Use your best judgement on when to ask for approvals.
Whenever reasonable, practice responsibility over rigidity. When you expect a page owner will appreciate your changes, go ahead and merge them without approval. Always ping the code owners with an @mention comment to inform them of the changes. They will be happy their page was made better and they didn’t need to waste time reviewing and approving the change. In the event that something isn’t an improvement, we practiceclean up over sign off.
Whenever appropriate, get approval from the code ownerusing the approval feature before merging changes. Each page in the handbook shows who the code owner listed under “Maintained by”. This information is pulled from the codeowners file. The page’s code owner is the DRI for the page and has the final say for what appears in the handbook. When in doubt, get the DRI’s permission before changing their page. Don't worry if the DRI is a C-level person. You can still assign your MRs to them, even if you are an individual contributor. This is because we prefer to communicate directly.
Unless it’s a small change like a typo, always have another team member review your changes before you merge them.
The www-gitlab-com project contains the blog, marketing website, and handbook. As a maintainer, you will have access to all three. In most cases, you should only merge changes to the handbook and loop in the marketing team for any MR related to the blog or marketing site.
For example, don’t merge blog posts without following the process outlined in the Blog handbook. Publishing on the marketing blog requires approval from the Editorial Team. Note, anyone can write and publisha blog post for NextGo’s Unfiltered Blog.
Similarly, don't merge website updates without marketing in the loop. Follow theinstructions for updating the website orrequesting help from the marketing team.
Being a maintainer gives you access to much more than just the ability to merge. You can see afull list of permissionsin the docs. Keep in mind that you’ll have access to a broad set of settings and configuration for the project. Don’t adjust any settings or make any structural changes without approval from themarketing Digital Experience team.
Do not grant people maintainer access without anAccess Request. As a maintainer you have the ability to grant others maintainer access. Don’t do so without following the Access Request process to garner the appropriate approvals and create the necessary documentation.