How to Deal with Team Documentation

Creating and Managing Your Team Handbook (🎁 Includes Template)

Writing documentation is undeniably one of the most tedious tasks, particularly when you, as an Engineering Manager, must promote it among your team.

When it comes to creating and maintaining your team’s documentation, this task becomes even more challenging. As an EM, you'd like to have well-structured, easily readable, and always well-maintained documentation for your team, but you often end up with scattered documents everywhere.

Been there, done that.

I can’t count how many different approaches I've tried over the years to achieve a good level of team’s documentation, and while I admit I'm not there yet, in the last couple of years, I've put a decent amount of research and effort into it (and so my teams).

So today, I’m going to share with you:

• ❓ Why having team documentation is important

• 📚 The different types of documentation

• 🏗️ My approach to structuring team documentation

• 🎁 An example of a team handbook (including a Notion starter template for paid subscribers)

As always, we have a lot to cover, so let's get started!

❓ The Importance of Team Documentation

Having good team documentation from an Engineering Manager's point of view is crucial and acts as a significant booster for your team's growth.

There are several reasons for this:

• Documentation is your showcase: especially in larger organizations, people from other teams or departments will likely get to know you through the documentation you write.

• Documentation brings clarity and certainty: as the saying goes, "written in stone." It's true; something written is hard to forget. It provides a history of your journey and how you've evolved. It also serves as a single source of truth.

• Saves time: just think about onboarding new team members. This doesn't mean you should leave your new hires alone with the docs, but well-done documentation greatly assists in quickly understanding the big picture.

• Makes it easier to share publicly: good and modular internal documentation serves as an excellent starting point when you need to go public. It can easily be transformed into a Knowledge Base for your customers.

📚 Different Types of Documentation

There are mainly two categories of documentation and both of them have very different purposes and rules.

Internal Documentation

• 🌍 Audience: targeted at employees and internal stakeholders.

• 💬 Purpose: facilitates internal operations, decision making, communication, and knowledge sharing.

• 🔒 Confidentiality: contains sensitive, internal-only information.

• 💡 Detail and Technicality: highly technical or detailed, specific to internal needs.

• 🔄 Flexibility and Updates: frequently updated to reflect internal changes and developments.

• 🤝 Collaborative Nature: often developed and maintained through internal collaboration.

Internal documentation can be categorized into various types. The most important ones include:

• Process Guidelines: detailed descriptions of internal procedures and workflows.

• Technical Documentation: code documentation, system architecture documents, internal APIs.

• Meeting Minutes: records of discussions and decisions made in meetings.

• Training Materials: resources for employee training and development.

• Internal Policies: documents outlining company policies, HR guidelines, etc.

• Project Plans: detailed plans and roadmaps for internal projects.

External Documentation

• 🌍 Audience: aimed at customers, clients, partners, and the general public.

• 💬 Purpose: provides information about products, services, or company policies.

• 🔒 Confidentiality: generally non-confidential, designed for public access.

• 💡 Detail and Technicality: clear, understandable, and free of internal jargon.

• 🔄 Flexibility and Updates: more stable, with changes reflecting major updates or policy shifts.

• 🤝 Collaborative Nature: involves collaboration, often with a focus on user accessibility and compliance.

Examples of external documentation are:

• User Manuals: guides for using products or services.

• Product Guides: detailed descriptions of product features and specifications.

• FAQs: frequently asked questions to assist customers.

• Terms of Service/Privacy Policies: legal documents outlining terms of use and privacy practices.

• Marketing Materials: brochures, product sheets, and other promotional documents.

• Compliance Documents: documents that demonstrate compliance with external standards and regulations.

While we could dedicate entire articles to each category of internal and external documentation (and I don't exclude to do so in the future), our focus today is on creating a robust and maintainable structure for your team's documentation.

🏗️ How to Structure Team Documentation

While there's no one-size-fits-all approach to structuring your team’s documentation, certain principles can guide its creation to ensure it's effective and user-friendly.

Let’s define them:

1. Logical Flow and Organization: arrange the content in a logical sequence. Start with an overview or introduction, proceed through the main content in a well-ordered manner, and conclude with appendices.

2. Starting with a Clear Purpose: identify the main goal of your documentation. Is it to instruct, inform, persuade, or document a process? The purpose should shape its structure.

3. User-Centric Design: consider who will be reading the document. Use language, examples, and references that resonate with your audience. For internal documents, this might mean using specific jargon familiar to the team (even if I’d suggest to avoid jargon as much as possible), while external documents should be more accessible to a general audience.

4. Utilizing Headings and Subheadings: break the content into manageable sections. This not only makes the document more readable but also helps in quick navigation.

5. Incorporating Visuals When Appropriate: as you know I’m a big fan of visuals. Diagrams, charts, and images can greatly enhance understanding, especially for complex topics. They provide visual breaks in the text and can make abstract concepts more concrete.

6. Consistency in Style and Format: use a consistent style and format throughout the document. This includes font choices, color schemes, and the style of writing. Consistency makes the document easier to follow.

7. Accessibility and Searchability: ensure that the document is accessible to all intended users. This can mean considering different formats or platforms and ensuring that the document is easily searchable, especially for longer documents.

8. Regular Updates and Maintenance: documentation is a living entity. Regularly review and update it to ensure it remains relevant and accurate, reflecting the latest changes and insights.

By following these principles, you can create documentation that is not only informative but also engaging and user-friendly. Remember, the best documentation meets users' needs and serves as a reliable source of information and guidance.

The Team Handbook Approach

When I think about the ideal team documentation, the example that always comes to mind is the Gitlab Handbook. Over the years, I have drawn considerable inspiration from this approach while creating internal documentation in my department and teams.

While the Gitlab Handbook covers a wide range of topics at the company level, you can easily adapt a similar approach on a smaller scale to manage your team's documentation.

To adhere to the first principle mentioned earlier, we'll draw inspiration from the Johnny.Decimal system. I've previously mentioned this system in other articles in the newsletter (I'm a big fan of it), and in my opinion, your Team’s Handbook is the perfect use case.

In essence, this method involves establishing 10 main categories, each containing up to 10 specific areas. Within these areas, you can then create an unlimited number of individual items. This approach helps in maintaining the handbook's conciseness and ease of use.

Main Categories

The first thing you want to do when you create your team’s handbook, is to define the 10 main categories your documentation should cover.

Let’s do that.

00. Index

10. Introduction

20. Team Overview

30. Policies and Procedures

40. Project Management

50. Technical Documentation

60. Tools and Resources

70. Performance and Development

80. Health, Safety, and Well-Being

90. Appendices

This is just an example, similar to what I use within my teams, but you can customize it based on your needs. The key is to maintain a limit of 10 categories.

Areas and Items

Now that we have the main categories, we can begin expanding them. Following the Johnny.Decimal principles, within categories, we could have:

• Areas: these are like subcategories, and you can have up to ten of them.

• Items: these are individual items, and you can have an unlimited number of them.

Let’s try.

00. Index
  00.00 The Index

10. Introduction
  10.1 About The Handbook <--- This is an Item
  10.2 Changelog
  11. Handbook Usage and Contribution <--- This is an Area (max 10)
    11.01. How to Contribute
    11.02. Handbook Style Guidelines

In this example, we took the 'Introduction' category and expanded it with some items, along with an Area ('Handbook Usage and Contribution') containing several items.

What Should Go in the Team’s Handbook?

If you were to ask me this question, my answer would be: everything. However, in reality, it depends on several factors. As we've seen, there are various types of documentation, and some may be more suitable to be included in the handbook than others.

Additionally, the choice of tools plays a role; for example, using Confluence or Notion to store API documentation might not be convenient. For these reasons, I have some general rules that I tend to follow:

• Store all high-level documentation in the Handbook, including design docs and technical specs.

• Low-level documentation, such as API docs and similar materials, can be stored outside the handbook, but they should be linked within it.

• All resources external to the handbook should either be internally accessible, or there should be provided documentation explaining how to request access to them.

Who writes the handbook?

Ideally, the handbook should be a collaborative effort, with active participation from every member of the team. This approach ensures that the handbook reflects the collective knowledge and expertise of the entire team and promotes a sense of ownership and commitment.

Here are some key suggestions to facilitate the creation of a comprehensive and inclusive handbook:

• Start Small, Expand Gradually: begin with essential topics and gradually add more sections as needed.

• Assign Responsibilities: designate team members to oversee specific sections, ensuring expertise and accountability.

• Involve Newcomers: encourage new members to contribute their insights and experiences to improve onboarding.

• Provide Clear Guidelines: establish formatting guidelines and templates for consistency.

• Allocate Specific Time: dedicate regular slots for handbook development and consider it when estimating workloads.

• Promote Contribution: foster a culture where everyone feels empowered to add to the handbook.

🏁 TL;DR

To summarize:

• 📌 Writing documentation, especially as an Engineering Manager, can be challenging and often results in scattered documents.

• 📜 Good team documentation is crucial for showcasing your team, bringing clarity, saving time, and facilitating public sharing.

• 📊 There are two main types of documentation: internal (for employees) and external (for customers/public).

• 📝 Structuring team documentation involves logical flow, clear purpose, user-centric design, headings, visuals, consistency, accessibility, and regular updates.

• 📈 Consider adopting a structure like Johnny.Decimal for your Team's Handbook with 10 main categories and areas/items within them.

• 📚 Store high-level documentation in the handbook, link to low-level documentation, and ensure access to external resources.

• 🤝 Encourage collaboration in handbook creation, allocate specific time for it, and promote contribution from all team members.

🎁 Team Handbook Notion Template (Paid Subscribers Only)

Starting from a blank page can feel daunting, especially if you're a first-time manager or a seasoned one looking to embark on this new journey with your team.

That's why I've created a Notion template based on the Johnny.Decimal structure we discussed earlier. I've also included some sections, partially filled with the help of ChatGPT, to provide you with a starting point for building your Team’s Handbook.

This template offers a simple example of how you can structure it, but feel free to customize it by adding different categories and areas that you find useful for your team.