Skip to content
Ido on GitHubIdo on Twitter

Engineering Handbook

When we decided to make a fully remote company, it was crystal clear that we would need a company handbook. A set of documents to describe how we work at, behaviors we appreciate, processes, faq, and more. We dedicated quite some time to writing, and we still are, making sure it is up-to-date. The handbook was proven beneficial to new hires and something they always appreciated. For some reason, I never did the same for the engineering until a few days ago.

We're about to apply a new organizational change in our engineering group, moving from domain-based teams (frontend/backend) to cross-functional teams. This is a topic for another day. This org change could be an excellent opportunity to streamline the processes and normalize how we work at our engineering group. To give you perspective about our current scale, we're two teams, 14 people (including myself) of different rules, team leads, web developers, go developers, and a data scientist. There are not too many people, but still big enough that every team will adjust to a slightly different culture. As mentioned, I wanted to normalize the culture and behavior among the different teams to make collaboration between different engineers easier, have better onboarding, and increase overall satisfaction.

Together with the team leads, we started putting together an engineering handbook. It's still a work in progress, but it includes the following sections:

  • Expectations - A short list of critical behaviors/traits and why we believe they're the key to having great work relationships, trust, and freedom to operate. We decided to focus on ownership, proactiveness, and predictability. I won't go into how we define them precisely, but these three were proven to be highly correlated with top performers in our case. Besides describing the expectations, we also provide example use cases with the expected and unexpected behavior. We curated these examples from real-life scenarios.
  • Decision records - They go by many names (ADR, RFC, decisions records), but every feature goes through a system design phase. During this phase, the epic owner describes how they will build the epic. Again, we've seen different forms of DRs, and we tried to pick the best. This section provides best practices and guidelines on writing good DRs with some examples, the review process, and more.
  • Epic owner and individual contributor - Two sections describing these different roles and responsibilities. To learn more, head to my blog post about our epic owners and ownership.
  • Communication preferences - Best practices for effective team communication and collaboration with non-engineering stakeholders.
  • Project management - Lastly, a section describes our approach, combining agile and waterfall. Here, we mention the sprint length, different rituals, time estimations, how we use Jira, etc.

It's still a work in progress, and I'm sharing this process with you early on. So, I don't have feedback to share yet, but hopefully, I will in a few months. I can say that we did our best to reflect on how we worked so far, learn what works and what doesn't, and document it properly. Especially in a remote environment, documenting it is crucial for the success of the engineering organization and individual engineers.

Last but not least, it's essential to keep this document up-to-date and clarify that it's a group effort. We will ask new hires to apply necessary edits, just like we do with our company handbook, and other engineers to provide feedback where they see fit.

Let's keep the discussion goingJoin my squad