Skip to content

Documentation Governance

Standards and processes for maintaining high-quality, consistent documentation across the Odoo 15 ERP system.

Document Ownership

Each documentation section has designated owners responsible for accuracy and currency:

Section Owner Review Cycle Scope
Getting Started DevOps Quarterly Installation, configuration, quickstart
Modules Development Per Release Module documentation and configuration
Field PWA Development Per Release PWA features and setup
Landing Page Development Per Release Landing page configuration
API Reference Development Per Release API endpoints and authentication
Operations DevOps Monthly Deployment, backup, security
Development Tech Lead Quarterly Standards, guides, contributing

Document Standards

File Organization

docs/content/
├── index.md                    # Main landing page
├── getting-started/
│   ├── index.md               # Section overview (required)
│   ├── installation.md
│   ├── configuration.md
│   └── quickstart.md
├── modules/
│   ├── index.md               # Section overview (required)
│   └── [module-name].md       # One file per module
└── ...

File Naming

Rule Example
Lowercase with hyphens module-name.md
Match navigation structure getting-started/installation.md
No spaces or special characters backup-recovery.md not backup & recovery.md
Descriptive names xero-integration.md not xero.md

Document Structure

Every document should follow this structure:

# Page Title

Brief introduction (1-2 sentences).

---

## Section 1

Content...

---

## Section 2

Content...

Required elements:

  1. Title (H1) - Clear, descriptive title
  2. Overview - Brief description of purpose
  3. Prerequisites (if applicable) - What's needed before following the guide
  4. Main Content - Organized with H2/H3 headers
  5. Examples - Code samples where relevant
  6. Related Links - Cross-references to related documentation

Writing Standards

Tone and Voice

  • Use active voice and direct language
  • Write for the reader's perspective (use "you" not "the user")
  • Be concise - every sentence should add value
  • Use consistent terminology (refer to Glossary)

Code Blocks

Always specify language for syntax highlighting:

# Python example
def hello():
    print("Hello, World!")

# Bash example
./production_deploy.sh start

# YAML example
services:
  odoo:
    image: odoo:15

Tables

Use tables for structured data with clear headers:

Column 1 Column 2 Column 3
Data Data Data

Admonitions

Use MkDocs Material admonitions for callouts:

!!! tip "Pro Tip"
    Helpful suggestions and best practices.

!!! warning "Warning"
    Important cautions and gotchas.

!!! note "Note"
    Additional context or information.

!!! info "Info"
    Informational content.

Review Process

New Documentation

  1. Create document following standards above
  2. Submit PR with docs: prefix in commit message
  3. Reviewer checks:
  4. Accuracy of technical content
  5. Adherence to formatting standards
  6. Working code examples
  7. Valid cross-references
  8. Merge after approval

Updates to Existing Documentation

  1. Create branch for changes
  2. Update document content
  3. Submit PR with description of changes
  4. Review and merge

Review Checklist

  • Title is clear and descriptive
  • Overview explains purpose
  • All code examples are tested and working
  • All internal links are valid
  • No sensitive data exposed (API keys, passwords)
  • Formatting is consistent with standards
  • Spelling and grammar checked
  • Cross-references to related docs included

Version Control

Git Workflow

  • All documentation is tracked in Git repository
  • Changes are tracked via commits
  • Use conventional commit messages:
git commit -m "docs: add SSL certificate setup guide"
git commit -m "docs: update deployment commands"
git commit -m "docs: fix broken links in API reference"

Branching

Branch Purpose
main Production documentation
develop Integration branch
docs/* Documentation changes

Quality Assurance

Pre-Publish Checklist

Before publishing documentation:

  • Build docs locally: cd docs && mkdocs serve
  • Verify no build warnings/errors
  • Check all links work
  • Test code examples
  • Review on mobile viewport
  • Spell check content
# Build and check for broken links
cd docs
mkdocs build --strict

Local Preview

# Start local documentation server
cd docs
mkdocs serve

# Access at http://localhost:8000

Archival Policy

Deprecating Documentation

When documentation becomes obsolete:

  1. Add deprecation notice at top of document:
!!! warning "Deprecated"
    This documentation is deprecated as of [date].
    See [New Guide](link) for current information.
  1. Keep deprecated docs for minimum 6 months
  2. Move to /archive/ directory after deprecation period
  3. Update navigation to remove archived docs

Version History

Major documentation updates should be noted in commits:

git commit -m "docs: major update to deployment guide for v2.0"

Continuous Improvement

Metrics to Track

Metric Purpose Tool
Page views Understand popular content Analytics
Search queries Identify gaps in documentation Search logs
Support tickets Find unclear documentation Helpdesk
Time since update Identify stale content Git history

Feedback Collection

  • Monitor support tickets for documentation-related issues
  • Review search queries for common topics
  • Conduct periodic user surveys
  • Track documentation-related GitHub issues

Annual Review

Each year, conduct comprehensive documentation audit:

  1. Review all documentation for accuracy
  2. Remove or update outdated content
  3. Refresh screenshots and examples
  4. Verify all links are functional
  5. Update code samples for current versions
  6. Review and update glossary
  7. Assess documentation structure and navigation

Tools and Resources

Documentation Stack

Tool Purpose
MkDocs Static site generator
Material theme Documentation theme
Mermaid Diagrams and flowcharts
Markdown Content authoring