01 How to Contribute

How to Contribute to the Company Handbook

Purpose

This guide explains how to contribute to the Company Handbook, including creating new content, updating existing documentation, and maintaining the governance structure. It also provides and introduction and overview to what the Company Handbook is all about and why it exists.

The handbook.calab.ai acts as the authoritative source of truth for how we operate, build, deliver, and grow at Calab.ai.

Who Can Contribute

All company members can contribute to the Handbook. However, contributions are subject to review and approval based on the governance model:

1. Company Governance: Requires Leadership Team approval
2. Value Stream Content: Requires Value Stream Owner approval
3. Guild Content: Requires Guild Lead approval
4. Practice Content: Requires Practice Owner approval
5. Product Content: Requires Product Owner approval

Contribution Workflow

Quick Edit (Recommended for Small Changes)

Every page on the Handbook has an “Edit this page” link in the page header. This is the fastest way to fix a typo, update a paragraph, or make small improvements:

1. Click “✏️ Edit this page” on any Handbook page
2. GitHub opens the file in its web editor — make your changes directly
3. Click “Commit changes…” — GitHub automatically creates a fork and pull request on your behalf
4. Your PR is routed for review based on CODEOWNERS rules

No git knowledge required. This workflow is ideal for quick fixes and small updates. For larger changes (new pages, restructuring), use the full workflow below.

1. Identify Where Your Content Belongs

Use the content classification decision tree in Content Types to determine:

• What type of content you’re creating (Policy, Process, Procedure, Guide, Template, or Decision)
• Which Practice owns this type of content
• Where the file should be placed in the folder structure

2. Creating and Updating Content

Creating a New Value Stream or Management Practice

New Value Streams and Management Practices are created through automated scaffolding:

1. Go to the repository Issues tab
2. Select “Create Value Stream” or “Create Management Practice”
3. Fill in all required fields in the issue form
4. Submit the issue — automation will validate inputs, run MECE analysis, and create a Pull Request with the complete folder structure and populated files
5. Review the generated PR and make any needed edits

Creating Content Within an Existing Practice

For policies, processes, procedures, guides, templates, and decisions within an existing practice:

1. Use the appropriate template from content/_authoring/templater/ (available for decisions, Guilds, and Products)
2. Follow naming conventions:
   • Use descriptive names: Incident Response Process.md
   • Include version numbers if needed: Security Baseline Policy v2.0.md
3. Add proper frontmatter:

   ---
   page-status: draft
   created: YYYY-MM-DD
   owner: [guild-slug]
   type: [policy|process|procedure|guide|template|decision]
   ---

3. Submit for Review

1. Create a feature branch: git checkout -b feat/[description]
2. Add your changes: git add .
3. Commit with clear message: git commit -m "Add: [description]"
4. Push to remote: git push -u origin feat/[description]
5. Create a Pull Request

4. Review and Approval

• Content validation runs automatically on all PRs touching content/
• GitHub CODEOWNERS automatically assigns reviewers based on the file path
• Address any feedback from reviewers
• Once approved, your PR will be merged

Content Quality Standards

All contributions must meet these minimum standards:

Clarity

• Use clear, concise language
• Define acronyms on first use
• Include examples where helpful

Completeness

• Include all required sections from templates
• Link to related content
• Provide context and rationale

Consistency

• Follow existing patterns and conventions
• Use consistent terminology
• Match the style of similar documents

Maintainability

• Include metadata (owner, status, version)
• Add change logs for significant updates
• Set review cadences

File Naming Conventions

• Use descriptive names: Customer Onboarding Process.md
• Use Title Case for document names
• Avoid special characters except hyphens and spaces
• Include version in filename only for versioned artefacts: Policy v2.0.md

Linking Best Practices

• Use standard Markdown links for internal navigation: [Display Name](slug)
• The slug is the target filename without .md, spaces replaced by hyphens (e.g. [Operating Model](02-Operating-Model))
• For pages in different folders, use the path from content/ root: [GL04 Practices](02-Guilds/GL04-Technology-Guild/README)
• For links to specific sections: [Section](slug#heading-slug)
• Do not use Obsidian wikilink syntax ([[...]])
• Always link to related practices, processes, and templates
• Check links before submitting — verify with npx quartz build --serve for a local preview

When to Create New vs Update Existing

Create New When:

• The topic is genuinely new and distinct
• Creating a new version of a policy (archive old version)
• Adding a new decision (decisions are immutable)

Update Existing When:

• Refining or expanding existing content
• Fixing errors or outdated information
• Adding clarifications or examples

Getting Help

If you’re unsure where content belongs or how to contribute:

• Ask your Practice Owner
• Consult your Guild Lead
• Review Content Types taxonomy
• Reach out to the Leadership Team

Related Resources

• Knowledge Standards
• Decision Process
• Organization Structure
• Content Types Taxonomy

---

Version: 1.1
Last Updated: 2026-02-23
Maintained By: Leadership Team