Organise documentation by product, module and audience

1. Overview & Business Value#

This comprehensive operational guide details the architecture, business workflows, configuration parameters, and execution steps for Organise documentation by product, module and audience within SmartERP.

Readers look for documentation in three ways: by the product or module they use, by what they want to do, and by who they are. The catalog gives every page those three handles, so search, filters, navigation and coverage all work from the same data.

{screenshot:organize-documentation-overview-dashboard}

2. Prerequisites & Security Access Groups#

• Required Modules: smarterp_docs
• Security Groups:
  • Technical Documentation Architect (Technical ID: base.group_system)
  • Enterprise User (Technical ID: base.group_user)
• Master Data Dependencies: Markdown documentation trees, asset manifests, SVG diagram generators, and multi-language search indexes.

3. Step-by-Step Configuration & Execution#

Step 1: Navigating to the Module Interface#

1. Log into your SmartERP instance at https://smarterp.et/odoo.
2. Open the main App Switcher (grid icon in the top-left corner).
3. Select the Documentation Portal app icon.
4. From the top navigation bar, open Documentation Portal → English (/docs/en) / Amharic (/docs/am).

{screenshot:organize-documentation-app-switcher-navigation}

Step 2: Creating and Parameterizing Records#

1. Click the New button in the top-left control panel.
2. Complete the mandatory fields in the record form:
   • Page Title (Mandatory): Standardized title conforming to Diátaxis framework
   • Summary (Mandatory): Concise operational summary describing page intent
   • Diátaxis Type (Mandatory): Valid classification (how_to, tutorial, concept, reference, admin_guide)
3. Configure optional operational parameters and localized tags as required:
   • Audience (Optional): Designated user roles (Accountants, Engineers, Administrators)
   • Difficulty Level (Optional): beginner, intermediate, or advanced
4. Click the Save icon in the control bar to commit the record.

{screenshot:organize-documentation-record-creation-form}

Step 3: Validating and Processing Transactions#

• State Transitions: Execute operational state progression (Authoring → Local Offline Test Validated → Manifest Registered → Published Live).
• Ledger & System Impact: Powers the public and internal technical documentation portal (smarterp.et/docs) with sub-second rendering and dual-theme visual diagrams.
• Audit Verification: Automated recording of author ID, timestamp, and immutable revision history.

{screenshot:organize-documentation-transaction-processing-state}

The catalog#

Open Documentation → Catalog → Products and Modules. It is a tree:

Every node has an address (its slug). The page of a node is at /docs/en/p/<slug>. A node shows its pages and the modules under it. Pages are counted under the node they are about and under every node above it.

Versions#

A product can list the versions it documents, such as 17.0. Mark one as the latest: only one version per product can be. A page lists the versions it is true for; none means every version. Readers choose a version on the product page, and the choice follows them from page to page.

A page that does not apply to the version a reader chose, or to the latest, says so at the top and names the versions it does apply to.

Audiences, industries and tags#

• Audiences say who a page is for: administrator, accountant, developer and so on. The home page lists them, and each one opens the pages for that audience.
• Industries say which kinds of business a page matters to.
• Tags are free words. A tag typed on a page that does not exist yet is created.

All three are lists you manage under Catalog. They are filters in search and in the back office.

What to set on a page#

A page with no product takes its section's product, and then the product named in smarterp_docs.default_product.

From files#

A page file can carry the same classification in its front matter, so the files and the database agree. See Writing pages. The keys a file declares win over what was set in Odoo for a page that follows its file; the rest are left alone.

4. Advanced Configuration Points#

• Automated Actions & Scheduled Tasks (Crons):
  • Documentation: Auto-rebuild search index (smarterp_docs.ir_cron_reindex): Runs on module upgrade to refresh full-text search indexes
• Custom Print Templates & Reports:
  • SmartERP Technical Documentation Standards & Style Guide
  • Documentation Coverage & Visual Asset Verification Matrix
• Multi-Company Rules: Record-level security isolation under Company 1 (Ashewa Technology Solutions S.C.), preventing cross-company ledger leakage across parent and subsidiary legal entities.

5. Comprehensive Troubleshooting Matrix#