When you’re headed to a destination, you often have two choices. You either take the direct route or the scenic route. The metaphor of a scenic route describes a longer approach to reach the same destination, with a few interesting sights thrown in, and maybe some adventure. If the adventure’s all you’re in for, you can take scenic routes all the time. If your job depends on delivering something on time, though, you’re better off taking the direct route regularly. 

That metaphor holds true even for software development teams. A huge number of tech teams in the world aren’t even building software for their direct employers. They work in my industry - IT services. IT spending in 2021 was approximately 1.1 trillion dollars. To put that into perspective, it’s about double the GDP of a nation such as Belgium or Sweden or Thailand. And in IT services, timely delivery matters. Not that it doesn’t for product companies, but when your business runs on contracts and service agreements, efficiency is crucial.

So if I had to extend that metaphor we started with, it makes sense for most software development teams to take the direct route when possible. Yet, with basic documentation, a lot of teams; especially those with misconceptions of agility; choose the scenic route. There are too many meetings, closed email threads and instant messaging discussions to disseminate information that the team can just write once in a shared handbook. This makes repeated activities, such as onboarding, inefficient. It also makes day-to-day communication frustrating. People have to say the same thing in different meetings and chat rooms. Knowledge sharing is slow, information moves in bits and bobs, and those inefficiencies cause interruptions galore. 

As GitLab rightly says,

Daunting as it may seem, a handbook-first approach has many advantages, and will give your team a way to self-govern and self-organise. In this post, I’ll walk you through some ideas about what to include in such a resource and how you can create and maintain it. 

Focus on the change you can influence

All-remote organisations such as GitLab and Basecamp document everything about their company in a handbook. Changing your company will be hard; even if you’re influential. So I suggest focusing on your immediate team. Makers will experience immediate benefits from an asynchronous way of working, so documenting your practices and team information with the team in mind is a good starting point. The good news is that nothing succeeds like success itself. If you can implement this way of working successfully with your team, your handbook will become a blueprint for other teams in the organisation. Little by little, change will happen and before you know it, a thousand flowers will bloom.

Imagine your dev team as a mini-company. There are two parts of your functioning - the organisational context that lays down how you work together; and then there’s the content of what you work on together. You can use a similar model to structure your handbook. The diagram above is a way to visualise this content architecture. Let’s dive into a little detail.

Project context

This part of your handbook derives from several topics we’ve addressed so far on this website.

1. Overview. The problem you’re solving for industry context, stakeholder bios and any background information that’s useful for the team goes here.

2. Ways of working. Team values, guidelines, work agreements and communication protocols and response times go here.

3. Responsible, accountable, consulted, informed (RACI). As teams get larger and distributed, everyone can’t possibly do everything. Clear roles and responsibilities on projects help avoid confusion. RACI charts are a succinct way to describe these roles and responsibilities.

4. Operations. Depending on the team you are, there’ll be operational information that everyone on the team should have. For example, instructions on filling timecards; or steps to get access to specific resources; or for that matter, information about getting laptops serviced.  

5. Knowledge. Not only is this section useful for new members of the team, it’s also important to existing team members. Everyone can’t be familiar with every part of the project and referencing the information in a structured fashion speeds up learning for the team. This section should also provide a map of how to navigate the project content. 

Project content

Depending on the tools your team uses, this information can exist across systems. Therefore, the knowledge section of your project context should provide a way to navigate across systems and provide your team a bird's-eye view of your project’s structure. These are some of the most rudimentary components of your project content.

1. Codebases & pipelines. Code is at the heart of your project. You should have an up-to-date catalogue of your repositories and it should be clear to your team how they can generate the application. In a later article, we’ll discuss lightweight measures to document your codebase.

2. Backlog. The structured list of requirements your team is building should be here. It should be clear to the team how they can navigate this backlog and make sense of it.

3. Assets. From design documents, to prototypes, to research or design sprint outputs - all these artefacts add up to the story of your product. Catalogue these so your team can make sense of the part of the solution they’re dealing with at any point in time.

4. Secrets. You’re going to need access to SSH, API keys, passwords and other sensitive information. It should be clear within the team how you will access these securely. 

5. Roadmap. If you’ve made commitments to stakeholders or the market about what functionality or capabilities you’ll deliver in the immediate future, make these commitments visible to the team. Ideally, they should have provided input for this roadmap. Making the roadmap visible to the team allows everyone to own it.

Of course, you can think of other branches to this structure and each level of this structure will have its own structure as well. Much like someone has to pave the road before others travel on it, some people on the team will need to build out version one of the handbook, so others can benefit from it. This list is a starting point for that first version.

Tools you can use

On tech teams, tools are a topic of endless discussion. I always suggest using the tools that your team already has access to. Even if there’s a more efficient tool out there, if your company hasn’t signed up to it, you’ll have heaps of trouble.

1. Access control will be problematic. It is tough to keep information secure and you’ll end up taking on too much risk of inadvertent IP leakage.

2. Onboarding people is tough, because new tools are often unfamiliar tools.

3. Off-boarding people is also tough and if you don’t remove people when they leave the team, you’ll amplify your risks in (1) above.

4. You’ll have to maintain tools yourself and manage subscriptions and licences at the team level, which is just unnecessary overhead.

If your company doesn’t provide you with a basic set of collaboration tools, start with a workaround and make a case to get the right tools in place. The due diligence and sign up may take time, but once the new tools are in place, you’ll be able to translate the benefits outside the team as well. You don’t need fancy tools. GitLab, Confluence, SharePoint, Notion, Almanac - these are all good starting points. If you want to use modern tools that automate some of this effort, try CodeSee or Scribe. Good search tools like Glean can enhance the discoverability of your content, as can Google Cloud Search.

Start small, own collectively, be iterative

If you look at the various elements of project context and content, you’ll realise that putting together the first version of your handbook is just about a week’s effort. You don’t have to be perfect. Just get it out there. Once the handbook is in place, you need to maintain it just as you’d maintain a good road. Like we collect toll for the upkeep of a road, expect everyone in the team to update relevant sections of the handbook with time. Designate someone in the team as the handbook editor and, if it works for you, rotate the role. This’ll help build collective ownership as well and the direct route will always be more viable than the scenic route.

I hope this post helps you see why you should setup a more direct route to catalogue knowledge and information for the team. Without the direct route of the handbook, your team will be like the blind people and the elephant. Everyone will build their own mental model of the project, but the team will be none the wiser. Lay down the direct route, figure out a way for people to contribute to its upkeep and watch the blindfolds disappear.