Handbook for Software Teams

Gitlab has published their Handbook online. Each company, team and organization has a particular “culture”. Some aspects in this handbook definitely resonate with me. I’ll add my notes in italics.


We value results, transparency, sharing, freedom, efficiency, frugality, collaboration, directness, kindness, diversity, boring solutions, and quirkiness:

  • Results: We care about what you achieve; the code you shipped, the user you made happy, and the team member you helped. Do not compete by proclaiming how many hours you worked yesterday because we don’t want someone who took the afternoon off to feel like they did something wrong. Instead celebrate the achievements of yourself and your teammates. We want people to have the desire to ship.

Actually getting work done is what should matter.

  • Transparency: Be open about as many things as possible. By making information public we can reduce the threshold to contribution and make collaboration easier. An example is the public repository of this website that also contains this company handbook. Everything we do is public by default, for example the GitLab CE and GitLab EE issue trackers, but also marketing and infrastructure. Transparency creates awareness for GitLab, allows us to recruit people that care about our culture, it gets us more and faster feedback from people outside the company, and makes it easier collaborate with them. There are exceptions, material that is not public by default is documented in the general guidelines. On a personal level you should tell it like it is instead of putting up a poker face. Don’t be afraid to admit you made a mistake or were wrong. When something went wrong it is a great opportunity to say ‘what’s the kaizen moment here’ and find a better way without hurt feelings.

I’ll break this into external (outside the team or company) and internal (within the team) transparency. For Gitlab external transparency makes sense which does not apply in all business models. However within a team there are multiple benefits.

  • Freedom: You should have clear objectives and the freedom to work on them as you see fit. Any instructions are open to discussion. You don’t have to defend how you spend your day. We trust team members to do the right thing instead of having rigid rules.

Autonomy again

  • Frugality: Amazon states it best with: “Accomplish more with less. Constraints breed resourcefulness, self-sufficiency and invention. There are no extra points for growing headcount, budget size or fixed expense.”

This is similar to a personal finance tip of “living below your means”. When times become hard which they eventually will, the teams that have already operationalized working effectively with less are more likely to survive.

  • Collaboration: Helping others is a priority. You are expected to ask others for help and advise. Anyone can chime in on any subject. You don’t have to comply with all feedback but you should always take it seriously. An example is the inclusion of people from outside GitLab Inc. in the core team.

  • Directness: We try to channel our inner Ben Horowitz by being both straightforward and kind, an uncommon cocktail of no-bullshit and no-asshole.

  • Kindness: We don’t want jerks in our team.

  • Boring solutions: Use the most simple and boring solution for a problem. You can always make it more complex later if that is needed. The speed of innovation for our organization and product is constrained by the total complexity we added so far, so every little reduction in complexity helps. Don’t pick an interesting technology just to make your work more fun, using code that is popular will ensure many bugs are already solved and its familiarity makes it easier for others to contribute.

This one point is how I tend to make technical decisions. Picking a boring solution that works is usually the easiest path to shipping. With experience and common sense you can evaluate areas where you need to experiment and others you need to be constrained. Minimize risk while providing maximum value.

If there are no risks or experiments, then you are probably not doing anything that is really innovative. However not everything needs to be a research project.


Getting work done requires focus. Getting interrupted over slack definitely kills productivity. Even if you try to disconnect, there is always a sense that you are missing something. Prefer asynchronous communication.


All of this comes down to the Culture of the team. Netflix has published their seminal Culture deck which has similar concepts. Microsoft has reinvented itself after Satya Nadella. So what sort of team do you want to be a part of?