Building a Knowledge Base for Your Tech Team

Part of The PIRATE Way — Stories about scaling up engineering teams.

Photo by Kenny Eliason on Unsplash

Introduction: Embracing a Culture of Documentation

Confession Time: I am a staunch advocate of documentation. It’s a crucial pillar for any thriving team. But let’s be honest — documentation is often seen as daunting. My approach? Keep it pragmatic and consistent, and avoid falling into the ‘hero mode’ of documenting everything at once.

The key is picking a knowledge repository, whether Confluence, BitBucket, Google Docs, or my go-to, Notion, and documenting what matters. Two principles drive my approach:

1. Responsive Documentation: If a topic arises more than once, the following response should be a link to its documentation.
2. Knowledge Continuity: My goal is to ensure that if I leave suddenly, the knowledge will still be accessible and beneficial to the organization, eliminating the ‘bus factor.’

The Pitfalls of Poor Documentation

Inadequate documentation can lead to significant challenges:

• Challenging Onboarding: New employees often need help to navigate through essential information, delaying their productivity.
• Reliance on Key Individuals: A lack of thorough documentation creates an unhealthy dependency on certain team members, increasing their risk of burnout and putting the organization in a precarious position.
• Knowledge Transfer and Retention Issues: The absence of documentation leads to the loss of valuable insights when team members leave or change roles, resulting in repetitive work and inefficiency.
• Impediments to Growth and Scalability: For growing organizations, accessible and comprehensive documentation is vital. Inadequate documentation restricts team scalability and adaptability.
• Compromised Quality and Consistency: Without documented procedures and standards, inconsistent practices can emerge across teams, leading to a decline in overall work quality and increased errors.
• Productivity Setbacks: The absence of proper documentation can significantly waste time as employees search for information or rely on others for help, disrupting multiple workflows.

Research by Atlassian underscores that well-documented projects significantly enhance team coordination and project outcomes.

In essence, robust technical documentation goes beyond mere information recording; it ensures continuity, minimizes dependencies, upholds quality, and fosters a knowledge-sharing culture. It is vital for enhancing productivity, minimizing errors, and protecting organizational knowledge, thereby supporting growth and adaptability in a dynamic business landscape.

Structuring a Knowledge Base for Tech Organizations

Photo by Niklas Ohlrogge on Unsplash

The knowledge base of a technology organization is a critical asset. It should be structured to provide quick access to necessary information while supporting the organization’s workflow and culture. Based on my experience, here are some key elements that I would include when structuring the knowledge base.

1. Team Information

• Team Directory: List all team members with their roles and contact information, their time zones, and other additional context that might be relevant for the rest of the team.
• Roles Definition: Detailed descriptions of different roles within the team, outlining responsibilities and expectations.

2. Team Spaces (Tribe and Guilds)

• Individual Team Pages: Dedicated spaces for each team (or squad/pod) where they can store and manage their documentation, such as project plans, meeting notes, problem domain documentation, and others.

3. Strategy Documentation

• OKRs and Goals: A clear record of the team’s objectives, key results, or other strategic goals, providing visibility into what the department and particular teams strive to achieve, including historical periods.

4. Brand-Building and Marketing

• Brand Guidelines: Standards and practices for maintaining the brand’s integrity and consistency across various platforms and materials.
• Marketing Collaterals: Repository of marketing materials, case studies, and promotional content.

5. Hiring and Recruitment

• Open Roles and Job Descriptions: Current openings along with detailed job descriptions.
• Hiring Process and Scripts: Standardized processes and interview guidelines to ensure a consistent and fair hiring process.
• Onboarding Materials: Resources to help new hires integrate smoothly into the team.

6. Onboarding Guidelines

• Organizational Onboarding: General information about the department, operating principles, and additional behaviors on top of the company’s core values.
• Discipline-Specific Onboarding: Detailed guides specific to different organizational roles or technical disciplines.

7. ‘How To’ Guides

• Process Manuals: Step-by-step guides for standard organizational processes and tasks (The On-Call Program, Reporting a Bug, Reporting a Product Suggestion, etc.)
• Best Practices: Documented best practices and guidelines for various technical and non-technical activities.

The knowledge base will become the source of truth, the go-to place for members, but that doesn’t mean you need to document everything in the knowledge base. It can be a link to a repository if you prefer the technical documentation stored as part of your codebase.

8. Internal Knowledge Repository

• All-Hands Meetings: Recordings and notes from all-hands meetings.
• Knowledge Sharing Sessions: Archive of past knowledge-sharing talks, guild meetings, and other internal learning resources.
• Decision Records: Documentation of critical decisions made, including context and rationale.

9. Learning and Development Resources

• Training Programs: Information about available learning programs and how to enroll.
• Educational Content: Access online courses, workshops, and other educational materials.

10. Talent Development Material

• Performance Review Process: Guidelines and schedules for performance evaluations.
• Competency Frameworks: Detailed competency frameworks for different roles.

11. Team Building and Social Initiatives

• Event Guidelines: Instructions and policies for organizing team-building activities.
• Social Programs: Information about company-sponsored social events and activities.

12. Retention and Engagement

• Department Engagement Surveys: Explanation of purpose, process, and follow-up actions.
• Providing and Receiving Feedback: Encouraging regular feedback and responsiveness. And guidelines for constructive and open dialogue.
• Effective 1:1 Meetings: For managers and individual contributors, focus on effective communication and goal setting.

While the components listed above form a robust foundation for a knowledge base, it’s crucial to remember that there are no one-size-fits-all solutions in knowledge management. Every organization has its unique culture, processes, challenges, and goals, which must be reflected in how its knowledge base is structured and utilized.

Approaches to Technical Documentation: ADRs, RFCs, and Beyond

Background of ADRs and RFCs

Architecture Decision Records (ADRs) and Request for Comments (RFCs) serve as foundational methodologies in software development, focusing on decision-making clarity, team collaboration, and historical record-keeping.

• ADRs: Originating to capture pivotal software architecture decisions, ADRs chronicle the decision’s context, considerations, and consequences. Michael Nygard’s template is a prime example of an efficient and comprehensive ADR format, aiding future references effectively. (More at adr.github.io)
• RFCs: Evolving from a tool for Internet standard discussions, RFCs now facilitate proposals and collaboration on major changes or new features within software projects. They encourage broad team engagement in significant decision-making.

Effective Use of ADRs and RFCs

ADRs and RFCs are particularly beneficial for documenting crucial decisions with substantial software system impacts, such as:

• Major architectural choices like programming language or framework selection.
• Proposals for significant system changes or new feature additions.
• Recording decisions to ensure a clear rationale for future reference.

For content creation:

• ADRs should detail the decision context, evaluated options, and the chosen option’s rationale.
• RFCs must outline the proposed change, its impact, alternatives, and potential challenges.

Regarding review and approval:

• Initiate feedback early during the drafting phase, involving team members and stakeholders for initial insights.
• Encourage members to send pre-reads of ADRs/RFCs to facilitate initial feedback from more relevant stakeholders before the final discussion.
• Organize a focused 30-minute meeting for the final discussion and decision-making.
• Include relevant stakeholders in the approval process, from senior engineers to peers and interdepartmental representatives.

Decision Records for Non-Tech Decisions

Documenting organizational decisions using ADRs or DRs in dynamic startup environments is as crucial as technical decisions. These records capture the context and rationale behind choices related to organizational strategy, tools, processes, and more, fostering informed future reassessments.

• Scope: Employ ADRs/DRs for documenting essential decisions across various organizational facets, from tool selection for different functions to establishing data strategies and frameworks.
• Adapting to Evolution: Given the rapid change in startups, documenting decisions helps understand past choices in the context of growth and evolution.
• Future Decision-Making: Past decisions, documented with context, offer valuable insights for future decision-making processes in a changed organizational landscape.
• Documentation Strategy: Guidelines for effectively documenting non-technical decisions, including detail levels, structure, and clarity best practices.

This section would also highlight strategies for maintaining an organized and accessible documentation system that supports technical and non-technical decisions, fostering a culture of transparency and informed decision-making throughout the organization.

Choosing the Right Knowledge Management Tools

The choice of knowledge management tools is pivotal for team efficiency. These tools shape how teams interact with information, storing it and making it accessible and discoverable.

Wiki-style platforms like Confluence and Notion offer a user-friendly, encyclopedia-like structure. They excel in organizing long-form content such as guidelines and company policies. However, they can become overwhelming as the content volume grows, requiring careful management to avoid this.

Document-based systems like Google Docs are familiar and easy to use, making them great for collaborative editing. However, there may be better choices for managing large volumes of interconnected information, as the discovery and navigation of data within folder-based systems can be challenging.

Notion is a hybrid platform that blends the features of both wiki-style platforms and document-based systems. It’s adaptable and can handle a variety of content types. ClickUp is another player to consider, but it leans more towards project management and excels in task tracking rather than serving as a repository for long-form knowledge documentation.

Technical Documentation

Technical documentation describes the functionality, architecture, or implementation of a technical product or service. It can be used by developers, support engineers, and other technical stakeholders to learn how to use, maintain, and troubleshoot the product or service.

There are many types of technical documentation, such as README files, API documentation, System architecture documentation, Technical specifications, etc. We will only dig deep into the details of some of those types of documents since they all deserve a dedicated post.

In general, Engineers often prefer to keep technical documentation within code repositories. This is because code repositories offer branch protection and approval control over changes, essential for documentation closely tied to the codebase, such as README files or specific technical procedures. However, a centralized approach is more efficient for broader organizational knowledge, like coding standards and testing strategies. This could be a central repository for each discipline or programming language, supplemented with a code owners file to manage change approval rights.

It’s key to balance documentation across platforms. Critical technical details related to the code should reside in repositories, while more general organizational knowledge, policies, and guidelines are better suited for a knowledge base. This ensures that the correct information is accessible in the proper context.

Every repository should include a comprehensive README file with essential project setup and usage instructions. However, for overarching coding standards and testing strategies that span multiple repositories, a central location — either a dedicated repository or a section within a knowledge base — is more practical and efficient. This central repository can then be referenced within individual project repositories as needed.

A knowledge base is a centralized location for various organizational knowledge, making it more accessible for different departments and new hires. It’s where broader organizational knowledge, policies, and guidelines should live. However, it requires regular updates to ensure the information remains relevant and accurate.

There is no one-size-fits-all solution for knowledge management in tech teams. The choice of tools and where to document various information depends on the team’s specific needs, the nature of the projects, and the organizational culture. Finding the right mix of wiki-style platforms for general knowledge and repositories for technical specifics is often the key to effective knowledge management. The goal is to make knowledge accessible, up-to-date, and relevant, enabling teams to work more efficiently and cohesively.

Conclusion: Embracing Sustainable Documentation Practices

Photo by JV on Unsplash

Documentation often becomes overlooked, gradually accumulating into a significant ‘documentation debt.’ This oversight can impede team efficiency and hinder a product’s long-term sustainability. To navigate this challenge, it’s essential to adopt a consistent and sustainable approach to documentation, rather than sporadic, heroic efforts.

Crafting a Proactive Documentation Strategy

• Future-Forward Approach: Establish a clear strategy for documentation that includes guidelines on what needs documenting, where it should be stored, and who is responsible. This strategic approach ensures that documentation is not an afterthought but an integral part of the development process.
• Integrate Documentation into Daily Workflow: Documentation should be a seamless aspect of your daily work. This includes documenting alongside coding, updating documentation with product changes, and incorporating documentation reviews as a standard part of your development cycle.

Mitigating Existing Documentation Debt

• Apply the ‘Boy/Girl Scout Rule’: Improve existing documentation incrementally. Encourage team members to update or refine documentation whenever they encounter outdated or lacking areas.
• Dedicate Time to Documentation: Just as technical debt is addressed through refactoring, allocate specific times for updating and enhancing documentation. This can be integrated into your sprint planning or set as a routine maintenance activity.

Fostering a Culture of Documentation

• Promote Collaborative Documentation Efforts: Documentation is a collective responsibility. Foster a culture of knowledge sharing and cooperative editing to distribute the workload and elevate the overall quality of the documentation.
• Recognize and Encourage Good Documentation Habits: Regularly acknowledge team members who exemplify strong documentation practices. This recognition helps build a culture where high-quality documentation is valued alongside code quality.

Efficient Use of Knowledge Management Tools

• Choose Tools That Complement Your Workflow: Employ tools like Notion, Confluence, or Git repositories that align with your team’s needs and enhance your workflow.
• Ensure Documentation Is Accessible and Easy to Navigate: A well-organized knowledge base, where documentation is easily discoverable and accessible, can significantly reduce time wastage and frustration.

In conclusion, adequate documentation is about integrating a culture of consistent and sustainable documentation within your team. It involves embedding documentation into everyday processes, systematically addressing documentation gaps, and judiciously using appropriate tools. This approach transforms documentation from a burdensome task to a valuable asset that boosts team efficiency and ensures the longevity of your product. Remember, a team that values and maintains up-to-date documentation is a hallmark of maturity, efficiency, and resilience in software development.

Remember: This is a blog post from “The PIRATE Way” series.