Quick Answer
Document Odoo customizations using 4 methods: __manifest__.py for module overview, Odoo Knowledge App for business users, changelog.md for version tracking, and docstrings in Python code. Without documentation, your customizations become a liability—upgrades cost 2x more and bugs become unfixable.
Introduction: The "Bus Factor" Problem
Imagine this: Your lead Odoo developer, the only person who understands the 5,000 lines of custom code running your warehouse, wins the lottery (or gets hit by a bus) and leaves tomorrow.
What happens to your business?
If your customizations aren't documented, your business stops. Upgrades become impossible. Bugs become unfixable. You are held hostage by "spaghetti code."
⚠️ Reality Check: Documentation isn't just a "nice-to-have"; it is the only way to ensure your ERP survives long-term.
In this guide, we break down the 4 Best Ways to Document Odoo Customizations, bridging the gap between developers and business users.
Method 1: The __manifest__.py and README (The Developer's Bible)
Start where the code lives.
Every Odoo module has a __manifest__.py file. Too often, developers leave the description blank or write "Custom module." This is a crime.
The Best Practice:
Treat the Manifest description as the "Executive Summary" of the module.
What to include:
📌 Purpose: Why does this module exist? (e.g., "Overrides standard commission logic for Sales Team A").
📌 Dependencies: What other modules does this rely on?
📌 Key Features: Bullet points of added functionality.
{
'name': 'Custom Sales Commission',
'version': '17.0.1.0.0',
'category': 'Sales',
'summary': 'Overrides commission logic for Sales Team A',
'description': '''
Purpose: Custom commission calculation
- 5% commission if margin > 20%
- 2% commission otherwise
Requested by: Sales Director (Ticket #402)
''',
'depends': ['sale', 'sale_commission'],
'author': 'Braincuber Technologies',
}The README.rst:
For every custom module, include a README.rst file that contains:
📋 Deployment Instructions
How to install and configure the module
⚙️ Configuration Notes
Required settings and parameters
📖 Usage Examples
How the feature should be used
Method 2: The Odoo Knowledge App (The Business User Manual)
This is where you bridge the gap between technical code and business process. The Knowledge App is Odoo's native wiki tool.
The Best Practice:
Create a single "Customizations" article within the Knowledge App.
What to include:
📸 Screenshots: A visual guide for the user ("To approve a quote, click the green button here").
📝 Decision Log: Document why a customization was made (e.g., "We created a custom 'Region' field because the standard 'Country' field did not meet our reporting needs for APAC").
🔄 Process Flow: Detailed steps for the business process that the customization supports.
Example Knowledge App Article:
📄 Custom Sales Approval Workflow
Manager approval is now required for all quotes with a discount greater than 15%. This feature was requested by the CFO on 10/10/2024.
Last updated: Nov 2024 | Owner: Sales Operations
Method 3: The Change Log (The "Who, What, When" History)
Tracking changes is vital for compliance and debugging.
The Best Practice:
Maintain a changelog.md file in the root of your custom development repository. This is an official record of every code deployment.
What to include:
| Field | Example | Purpose |
|---|---|---|
| Date & Version | [2024-11-01] - v1.0.5 | When was it deployed? |
| Author | John Smith | Who made the change? |
| Ticket ID | JIRA-402 | Why was it requested? |
| Summary | Implemented automatic commission calculation | What was changed? |
# Changelog
## [2024-11-01] - v1.0.5
**Author:** John Smith
**Ticket:** JIRA-402
**Summary:** Implemented automatic commission calculation for Sales Team B based on new formula.
## [2024-10-15] - v1.0.4
**Author:** Jane Doe
**Ticket:** JIRA-398
**Summary:** Fixed discount validation bug in quote approval workflow.💡 Pro Tip: This file serves as a quick lookup for why a bug appeared on a specific date. Essential for debugging!
Method 4: Docstrings (The Code-Level Explanation)
The developer's primary responsibility. A docstring is a multi-line string placed immediately below a Python function or class definition.
The Best Practice:
Every custom method (def) must have a docstring explaining its purpose, arguments, and return value.
def _compute_sales_commission(self):
"""
Overrides standard commission calculation.
Logic:
- If margin > 20%, commission is 5%
- Otherwise, commission is 2%
Requested by: Sales Director (Ticket #402)
Added: 2024-11-01
"""
for record in self:
if record.margin_percent > 20:
record.commission = record.amount * 0.05
else:
record.commission = record.amount * 0.02Documentation Quick Reference
| Method | Audience | Location | Purpose |
|---|---|---|---|
| __manifest__.py | Developers | Module root | Module overview |
| README.rst | Developers/Consultants | Module root | Deployment & usage |
| Knowledge App | Business Users | Odoo UI | Process documentation |
| changelog.md | All Teams | Repository root | Version history |
| Docstrings | Developers | In code | Function-level logic |
Frequently Asked Questions
Why is documentation important for Odoo upgrades?
When upgrading (e.g., Odoo 17 to 18), standard code is updated automatically. Custom code breaks. If you don't have documentation explaining what your custom code does, the upgrade team has to reverse-engineer it line-by-line, doubling the cost of your upgrade.
Is there a tool to generate Odoo documentation automatically?
Yes. Tools like Sphinx (for Python) can read your docstrings and generate a professional PDF manual. However, this only covers technical documentation, not the business logic—that still requires manual documentation in the Knowledge App.
How often should documentation be updated?
Ideally, continuously. A "Definition of Done" for any development task should include "Documentation Updated." If the documentation isn't updated, the ticket isn't closed.
What is the "Bus Factor" in software development?
The "Bus Factor" refers to the number of team members who could leave (get hit by a bus, win the lottery, quit) before a project stalls. If only one person understands the code, your bus factor is 1—extremely risky. Good documentation increases this number.
Should business users write documentation too?
Yes! Business users should document the "why" (business requirements, decision logs) in the Knowledge App, while developers document the "how" (code logic, technical implementation). Both perspectives are essential for long-term maintainability.
Conclusion: Documentation is an Asset
Your Odoo customizations are intellectual property. If they aren't documented, they are a liability.
By using the Knowledge App, enforcing Manifest standards, and maintaining a Change Log, you turn your ERP into a sustainable, scalable asset.
Is Your Current Odoo Partner Leaving You in the Dark?
Let Braincuber map out your system. We turn black boxes into clear maps with comprehensive documentation and architecture reviews.
Schedule a System Architecture Review
We'll audit your customizations, create proper documentation, and ensure your Odoo system is maintainable for years to come.
Free assessment • Documentation audit • Clear roadmap