Creating a Company Handbook - Scalable, Text-Based, and Future-Proof

Creating a Company Handbook: Scalable, Text-Based, and Future-Proof

A company handbook is more than a collection of documents – it is the central nervous system of an organization. It creates transparency, makes knowledge accessible, and enables teams to collaborate efficiently. But how do you design a handbook that grows with the company, remains technically flexible, and works without proprietary tools?

This article shows how to build a handbook that is scalable, text-based, and version-controlled – from individual knowledge collections to enterprise-wide documentation systems. We rely on open-source formats like Markdown with Mermaid or AsciiDoc with PlantUML, as well as tools that support these approaches.

Why a Text-Based Company Handbook?

Traditional handbooks often fail at three points:

1. They are static and become outdated quickly.
2. They are difficult to maintain because they exist in closed formats (e.g., Word, Confluence).
3. They do not scale with the organization – what works for a small team breaks down in complex structures.

A text-based handbook solves these problems:

• Markdown/AsciiDoc as the base format enable easy editing, versioning, and automation.
• Diagrams as code (Mermaid, PlantUML) can be embedded directly into documents – without external tools.
• Version control (e.g., via Git) makes changes traceable and collaborative.
• Scalability: From an individual note-taking system to an enterprise-wide knowledge repository – the approach remains the same.

The Four Scaling Levels: From Individual to Enterprise

Based on the Digital Practitioner Body of Knowledge (DPBoK), four maturity levels can be distinguished that determine how a handbook should be structured:

1. Individual: Personal Knowledge Collection

• Goal: Individuals document their knowledge for themselves or a small team.
• Approach:
  • Simple Markdown files in a folder (e.g., knowledge/onboarding.md, knowledge/processes/sales.md).
  • Diagrams directly as Mermaid code within Markdown.
  • Version control via Git (e.g., GitHub, GitLab, Gitea).
• Tools:
  • Joplin (notes in Markdown with Mermaid support)
  • Logseq (networked knowledge with Markdown/Org-Mode)
  • Standalone Markdown editor (e.g., VS Code with plugins)

2. Team: Collaborative Documentation

• Goal: A team uses the handbook as a central knowledge base.
• Approach:
  • Central repository (e.g., GitLab, GitHub) with clear editing rules.
  • Automated preview (e.g., via MkDocs or DokuWiki).
  • Simple search function (e.g., via DokuWiki or Wiki.js).
• Tools:
  • DokuWiki (simple wiki solution with plugin support)
  • MkDocs (static documentation from Markdown, ideal for technical teams)
  • Wiki.js (modern wiki software with Markdown support)

Advantage: Changes are traceable, and the team can work together on documents – without lock-in effects.

3. Team of Teams: Cross-Departmental Usage

• Goal: Multiple teams use the handbook, and content must be consistent and interconnected.
• Approach:
  • Modular structure (e.g., by department or topic).
  • Linking between documents (e.g., “See Onboarding Process”).
  • Automated build pipelines (e.g., with GitLab CI/CD) to update documentation.
• Tools:
  • Antora (documentation for multiple teams/projects, based on AsciiDoc)
  • Wiki.js with plugins (for advanced search functions and permissions)

Example:
A development team documents its API in AsciiDoc, while the marketing team maintains its processes in Markdown – both are compiled into unified documentation in Antora.

4. Enterprise: Company-Wide Standardization

• Goal: The handbook becomes the Single Source of Truth for the entire company.
• Approach:
  • Structured metadata (e.g., YAML frontmatter for target audiences, validity date).
  • Automated checks (e.g., broken links, missing diagrams).
  • Integration into existing systems (e.g., search index with Elasticsearch).
• Tools:
  • Wiki.js with LDAP/SSO (for enterprise-wide authentication)
  • Antora + GitLab (for large, distributed documentation projects)
  • Custom solutions (e.g., static websites with Hugo or Sphinx)

Advantage: The handbook becomes a living knowledge database that scales with the company – without requiring technology changes.

Open-Source Tools Comparison: What Fits Your Maturity Level?

Practical Implementation: Step by Step

1. Choose Format: Markdown or AsciiDoc?

• Markdown is easier to learn and sufficient for most use cases.
• AsciiDoc offers more features (e.g., tables, cross-references) and is ideal for complex documentation.

Recommendation:

• Start with Markdown if you want to get going quickly.
• Switch to AsciiDoc if you need advanced features (e.g., for API documentation).

2. Define Structure

• Folder structure by topic or department:

handbook/
├── organization/
│   ├── roles.md
│   └── teams.md
├── processes/
│   ├── sales.md
│   └── development.md
└── it/
    ├── systems.md
    └── security.md

• Diagrams as code (example in Mermaid):

graph TD;
    A[Customer Inquiry] --> B[CRM Entry];
    B --> C[Quote Creation];

graph TD;
    A[Customer Inquiry] --> B[CRM Entry];
    B --> C[Quote Creation];

3. Set Up Version Control

• Create a Git repository (e.g., on GitHub, GitLab, Gitea).
• Define a branching strategy (e.g., main for published version, draft for drafts).
• Keep commit messages clear (e.g., “feat(onboarding): added note on home office policy”).

Example Workflow:

1. Change a file locally.
2. Commit the change with a meaningful message.
3. Push to the draft branch.
4. After review: Merge into main.

4. Select and Set Up Tool

• For small teams: Host DokuWiki or MkDocs on a server.
• For large teams: Wiki.js with LDAP integration or Antora with GitLab CI/CD.

5. Leverage Automation

• Build pipelines (e.g., GitLab CI) to automatically generate a preview upon changes.
• Webhooks to inform teams about updates (e.g., Slack message on new commits).

6. Establish Maintenance Processes

• Assign responsibles per area (e.g., “HR maintains onboarding documents”).
• Conduct regular reviews (e.g., quarterly check for outdated content).
• Implement feedback mechanisms (e.g., “Report” button in Wiki.js).

Advantages of the Text-Based Approach

1. Version Control

Every change is traceable – who changed what and when? If errors occur, it’s easy to revert to a previous version.

2. Collaboration

Multiple people can work on documents simultaneously (e.g., via pull requests in GitLab).

3. Automation

• Generate content (e.g., API documentation from code comments).
• Update diagrams (Mermaid/PlantUML re-renders with each build).
• Build search index (e.g., with Elasticsearch for Wiki.js).

4. Future-Proofing

• No lock-in: Markdown/AsciiDoc are simple text formats that are easy to migrate.
• Tool-independent: Content remains usable even if the tool changes.

Typical Challenges – and How to Solve Them

Conclusion: A Handbook That Grows With You

A text-based, version-controlled company handbook is not a project with an end date, but a living system that adapts to your organization’s needs. Whether you start as an individual or document a large company – the approach remains the same:

1. Start small with Markdown/AsciiDoc and a simple tool (e.g., Joplin or DokuWiki).
2. Scale gradually with Git, Antora, or Wiki.js.
3. Automate builds, updates, and notifications.
4. Maintain continuously – a handbook is never finished.

Your next step:

• Try Markdown in a small project (e.g., with VS Code or Joplin).
• Set up a Git repository for your documents.
• Choose a tool that fits your maturity level – and start documenting.

Resources for Further Reading

• Markdown Guide
• Mermaid Documentation
• AsciiDoc Handbook
• Antora Documentation
• Wiki.js Handbook

• ←Previous
• Next→