Skip to content

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.

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.

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.

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.

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.

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.

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.