eBiz Documentation — Design & Contribution Guide¶

This directory is the canonical knowledge base for the eBiz platform. It is written for two consumers with equal priority: humans browsing the rendered site, and the AI assistant's retrieval pipeline (RAG). Every rule below exists to serve one or both.

Core principles¶

Content over platform. The corpus is plain markdown in this repo. The renderer (MkDocs Material) and the retrieval pipeline are both replaceable; the markdown is the asset.
One page = one retrievable answer. A page should answer a question standing alone. If a page needs a table of contents, split it.
Structure by domain object, audience by metadata. There are no per-audience folder trees. Audience lives in frontmatter and is used for retrieval filtering.
Docs change in the same diff as the code they describe. A PR that changes calculation logic or permission checks must update the corresponding reference page (or carry a docs-exempt label).
Write for machine retrieval. Pages are self-contained: no "as mentioned above", no cross-page pronouns, assumptions stated per page.

Directory structure¶

docs/
  overview/       domain-level orientation ("what deals are", "financials")
  concepts/       what things ARE and how they behave (audience-agnostic)
  tasks/          how to DO specific things (audience-tagged)
  reference/      settings, permissions matrix, field definitions, calc rules
  tenant-notes/   group-specific behavior, one file per tenant
  _templates/     copy these to start a new page
assets/           images, in per-page subfolders: assets/<page-slug>/

Class then domain. The first level is the content class (above). concepts/ and tasks/ are further grouped one level deeper by feature domain — a subfolder such as deals/, financials/, documents/, companies/, communications/, procurement/, or system/ — giving class/domain/page.md. The domain subfolder is navigation only; a page's class and type still come from its top-level class dir and frontmatter. overview/ and reference/ stay flat (class/page.md); overview/ is a small set of one-per-domain orientation pages.

Maximum depth: three levels (class/domain/page.md). Never four. Add a new domain subfolder rather than letting a class dir grow past ~10 flat files.

Content classes¶

Class	Purpose	Audience handling
`overview`	Domain-level orientation: what a whole area (deals, financials, documents…) is and how its pieces fit, linking down into concepts/tasks	One page per domain; all audiences
`concept`	Explains an object: what it is, how it behaves, why it changes, what it is NOT	Usually all audiences
`task`	Step-by-step instructions for one action	One page per (action, audience) pair, only where behavior differs
`reference`	Mechanical truth: permission matrix, field definitions, calc rules, status enums	Extract from code where possible; keep in sync via CI
`tenant-note`	Per-group configuration semantics and deviations	Tagged with tenant ID; filtered/boosted at retrieval time

Concept pages should include a "Why does X change unexpectedly" section (the real support question) and a "What X is not" section (disambiguation from adjacent features — critical for retrieval quality).

Frontmatter schema (required on every page)¶

---
title: Creating a deal            # sentence case, human-readable
type: task                        # overview | concept | task | reference | tenant-note
object: deals                     # deals | rebates | allocations | projections |
                                  # contacts | news | files | permissions | tenants |
                                  # products
audience: [administrator]         # administrator | superuser | consumer (list)
tenant: all                       # all | nbg | fortis | phg | hb | ...
permissions: [deal.create]        # platform permission keys required, [] if none
last_verified: 2026-07-17         # date content was confirmed TRUE, not last edited
---

CI lints this schema on every PR (missing fields or out-of-enum values fail the build). Update last_verified only when you have confirmed the content against current platform behavior.

Naming and linking¶

Filenames: object-action.md for tasks (deals-create.md), object-topic.md for concepts (deals-lifecycle.md). Lowercase, hyphenated. Never rename a published file — filenames are stable IDs used as chunk anchors and citation targets. Moving a file into a domain subfolder is allowed (the basename is the ID, not the path), but do it before publishing since the path change breaks existing links.
Links: relative file paths only, resolved from the linking page's location — e.g. from overview/overview-deals.md, link a concept as [the deal dashboard](../concepts/deals/deals-dashboard.md). Never absolute URLs to the rendered site. CI dead-link-checks these.
Images: assets/<page-slug>/<name>.png. Use sparingly — every screenshot is a maintenance liability and contributes nothing to retrieval. Prefer describing the field ("set Rebate Basis to Net Invoiced") over showing it.

Writing rules¶

Self-contained pages: a reader (or a retrieved chunk) needs no other page to make sense of this one. Link for depth, don't depend on it.
Explicit headings that match the questions users ask.
Placeholder convention: mark unverified or assumed behavior with an HTML comment  rather than guessing silently. These are tracked and must be resolved before last_verified is set.
Tenant-specific behavior never goes in concept/task/reference pages — it goes in tenant-notes/ with a link from the general page.
No versioned folders. The platform is SaaS with one live version; configuration variance is a tenant-notes concern.

Build and deploy¶

Renderer: MkDocs Material. Config in mkdocs.yml at repo root. Build output (site/) is gitignored.
Local preview: pip install mkdocs-material && mkdocs serve
CI (path-filtered to docs/**):
frontmatter schema lint
dead-link check
mkdocs build --strict
deploy static site on merge to main
trigger RAG re-index on merge to main

Priority order for new content¶

reference/permissions-matrix.md and reference/rebate-calculation-rules.md (highest AI value, partially extractable from code)
Concept pages for core objects (deals, rebates, allocations, projections)
Administrator task pages
Superuser task pages
Consumer pages last (thinnest surface, mostly self-evident)