Documentation standard

This page is the standard for all SmartERP documentation. It is written for the people who write and review pages, and it is public so that customers can see what they can expect from every module.

Principles#

SmartERP documentation follows the principles of three well-established references. It does not claim formal certification against them.

For wording we follow the plain-language guidance of the Microsoft Writing Style Guide and the Google developer documentation style guide: short sentences, active voice, present tense, second person ("you").

Audiences#

Every module is documented for the audiences that use it. Say who a page is for in its first sentence.

The standard page set#

Every module family gets one section. Use these pages in this order. Leave a page out only when it truly does not apply (a module with no portal has no Portal guide), and say so in the overview.

The section's _section.md gives it a title and a one-line summary. When a family has several modules, one module owns the section (and its _section.md); the other modules add their pages to the same section without a _section.md, as described in Document your own module.

Writing rules#

Titles and headings#

• Task pages start with a verb: "Create a shift template", not "Shift templates".
• Concept pages use a noun phrase: "How shifts are allocated".
• Start headings at ## and keep them in order. Give an explicit address, such as {#guardrails}, to any heading other pages link to.

Steps#

1. Say what the reader needs first (a role, a setting, existing data).
2. Number the steps. One action per step. Put the result after the step that causes it: "The shift turns green."
3. Name every button, menu and field exactly as the screen does, in bold. Check the label against the running system, never from memory.
4. End with what the reader can do next, using a doc: link.

Voice and words#

• Use "you", present tense and active voice.
• One term for one thing. Use the term in the Glossary, and add new terms there.
• Avoid "simply", "just", "obviously" and "easy". Avoid idioms: many readers use English as a second language.
• Write numbers and dates unambiguously (2026-09-15, "15 September 2026"). Show money with its currency (12,500 ETB).
• Put commands, file names, field names and menu paths in code or bold as appropriate, and quote error messages exactly, because people search for the text they see.

Warnings come first#

Put a callout before the step it applies to, never after. Use [!WARNING] for something that can go wrong, [!CAUTION] for data loss or money, and [!IMPORTANT] for something the reader must not miss.

Accuracy rules#

Documentation that is wrong is worse than none. These rules are not optional.

1. Derive every statement from the module itself: its manifest, models, views, security files, wizards, scheduled actions, tests, and the running system. If you cannot find it there, do not write it.
2. Do not invent. No made-up features, limits, prices, performance figures, certifications or legal claims. A statement about Ethiopian tax, pension or labour law must name its source or be left out.
3. Say what the module does not do when a reader would reasonably expect it. Limits and known gaps belong in the documentation.
4. Quote labels and messages from the code (string= attributes, view XML, _("...") messages) and confirm them on screen.
5. Record doubts in the section's review notes instead of guessing in the page.
6. Every module version is stated as "applies to 17.0.x". Pages that describe behaviour that changed between versions say so.

Screenshots#

• Demo data only. Never capture real customer, supplier, employee, salary, bank or contact data. Use the records labelled [DEMO], or create new demo records that are labelled the same way. The screenshot tool scans for emails, keys and phone numbers, but it cannot recognise a real person's name, so you must choose the screen carefully and use mask for anything doubtful.
• One screenshot should prove one point. Crop to the relevant area (capture with a selector) and number the call-outs (annotate).
• Size 1280 by 760 for full screens. Keep each file under the 250 KB budget.
• Give every image alt text that describes what the reader would see, and a caption that says why it is there.
• Name the asset <family>-<what>, for example planning-schedule-week.
• Shot lists live in smarterp_docs/shots/<family>.json. See Screenshots.
• Retake screenshots after a change to the screens: python3 smarterp_docs/tools/shots.py --check lists the stale ones.

Diagrams#

Every module family has at least:

• a workflow diagram for each main process, in swimlanes by who does the work (user, approver, system);
• a status diagram for each record that has statuses;
• in the technical reference, a module map (which module depends on which) and a data-model diagram of the main models.

Keep a diagram to about nine boxes. If it needs more, split it. Diagram specs live in smarterp_docs/diagrams/<family>.json and are drawn by smarterp_docs/tools/diagrams.py, so they match the site's look in light and dark mode. Always add the same steps as text, because a diagram is not a substitute for words.

Review and quality gate#

A section is finished when all of these are true:

• Every page in the standard set exists, or the overview says why not.
• Every statement was checked against the code or the running system.
• Every task was walked through on the pilot using only the page, and it worked.
• Screenshots use demo data and show the current screens.
• python3 smarterp_docs/tools/run_offline_tests.py passes: no broken links, every page has a summary, headings are in order.
• The pages read cleanly on the site at /docs, in light and dark mode.
• A second person (or a fresh reader) followed the Quick start without help.

Languages#

Sections are written in English first. Once an English section is reviewed and stable, it is translated into Amharic page by page, and a native reader checks the result before release. A section joins the translation-parity tests as soon as its first Amharic file exists. See Translating.