Documentation structure
The documentation is organized into system areas, topics and detailed references. Each topic answers a specific reader question. The topic map records that question, the article type and the topic’s current address.
Page boundaries
Section titled “Page boundaries”| Level | Content | Working range |
|---|---|---|
| Documentation index | System definition and navigation by area | A short introduction and area links |
| Area overview | Responsibility, scope and summaries of its topics | About 150–350 words before topic summaries |
| Topic article | One coherent concept, mechanism or task | Usually 400–1,000 words |
| Detailed reference | Exact fields, contracts, states or error codes | As much as the reference requires |
These are Toolora planning ranges, not Microsoft requirements or validation limits. Shorter summaries are appropriate while an area is being established. A complete reference may be longer. Document usefulness determines the boundary.
Create a page when a subject has an independent reader question, needs a direct link or changes independently of surrounding content. Use a heading for a short explanation that belongs to the current question. Avoid one page per code file and avoid splitting a cohesive explanation merely to meet a word count.
The usual visible hierarchy is area, topic and, where needed, a detailed reference. Frontend, API and database information can occur in one business explanation when it is necessary to follow the same operation across its boundaries.
Article types
Section titled “Article types”| Type | Required content | Template |
|---|---|---|
| Overview | Definition, scope, topic summaries and links | Overview |
| Concept | Meaning, behaviour, relationships, rules and limits | Concept |
| Procedure | Prerequisites, actions, expected result and failure handling | Procedure |
| Reference | Exact values, contract, constraints and errors | Reference |
| Troubleshooting | Symptom, evidence, diagnosis, correction and verification | Troubleshooting |
Choose headings for the article’s subject. The area-level checklist in the section template covers the complete area; it does not require every article to repeat all of those headings.
Initial summaries
Section titled “Initial summaries”Each registered topic has a factual summary at its current address. The summary states what the subject is, its responsibility or behaviour, and its main relationship or boundary. Two to four sentences are usually sufficient.
A summary must contain supported facts. Do not fill it with promises about a future article. Missing detail belongs in the coverage register and review scope. Uncertain behaviour remains explicitly uncertain. The initial summaries do not constitute complete API references or business-flow verification.
Topic addresses
Section titled “Topic addresses”Topics initially have named sections within area pages. Their addresses are real
published page-and-anchor links. The register does not publish speculative URLs
for unwritten articles. Each topic has a stable logical ID independent of its
display title, for example access/customer-portal.
When a topic receives a separate article, retain the old anchor with a short summary and link to that article. Update the topic’s canonical address in the register and relevant cross-links. Preserve existing links in distributed editions. Changing a heading requires checking its registered anchor.
Links between topics
Section titled “Links between topics”Each central concept has one owning explanation in the documentation. Summarize it where context requires and link to its owner for detail. For example, quote acceptance links to billing basis rather than repeating the complete invoicing contract.
- Link a concept at its first relevant occurrence in an article. Repeat the link later only when it helps the reader at that point.
- Use the destination’s subject as link text. Avoid generic labels such as “click here” and “read more”.
- Use a section anchor when the reader needs a particular part of a longer page.
- Link each area from the documentation index. Each article must also have a parent or other content link, independently of generated navigation.
- Add links between areas when the text explains a real relationship, dependency or constraint. Link density is not a target.
- Use a short related-information list for useful adjacent subjects.
Keep reading links separate from source evidence. Internal links connect the system explanation. The source details identify code, contracts and tests at a specific revision. Existing topic contracts and CONTEXT.md retain their authority; a handbook explanation does not create another operational contract.
Structure checks
Section titled “Structure checks”The handbook verification checks registered pages and anchors, topic IDs and relationships, parent/content reachability, article types and source references. It also checks generated links and local assets. An author still reviews whether the question, summary and cross-links describe the correct subject.
See Writing style for language and Evidence and coverage for review status.