Writing style
Toolora documentation describes system behaviour, conditions and responsibilities in plain English. The writing model is Microsoft Learn’s technical articles and the Microsoft Writing Style Guide. The conventions below apply those principles to this repository; they do not reproduce Microsoft’s brand or page design.
Opening paragraphs
Section titled “Opening paragraphs”Start with the subject’s definition or behaviour. State the applicable scope early. Describe the system before discussing how its documentation was produced. Keep authoring instructions, delivery history and coverage administration on their own pages.
For example:
The customer portal requires an authenticated user. The API checks access to the requested project before returning customer-visible information. Project access and publication are separate checks. Adding a contact or a ROT recipient does not grant portal access.
The example illustrates tone and scope. The detailed customer-portal article must establish the complete access rules from its owning implementation.
Sentences and terms
Section titled “Sentences and terms”Use active voice and name the actor: “The API checks the invoice revision.” Use present tense for current behaviour. State proposals and intended behaviour as proposals rather than describing them as implemented.
Use one term for one concept, following CONTEXT.md. Explain necessary technical terms at first use. For example, row-level security (RLS) is database policy that constrains which rows a caller may access. Later references can use RLS.
Keep sentences and paragraphs short enough to follow without losing conditions. Use precise verbs such as checks, stores, returns, rejects and publishes. Avoid claims such as powerful, seamless or robust; describe the mechanism or observed property instead. Keep examples synthetic and relevant to the stated behaviour.
Headings and formatting
Section titled “Headings and formatting”Use sentence case and descriptive headings. Concept and reference titles name the subject. Procedure titles name an action. Troubleshooting titles identify the symptom or failure. Use parallel wording for sibling headings.
Start page sections at level two and use level three when there are multiple distinct subtopics. Do not skip heading levels or add filler between headings. Use numbered lists for ordered actions, tables for comparisons and contracts, and bullets for parallel facts. Emphasize UI labels consistently in procedures; format code identifiers and exact values as code.
Rules and uncertainty
Section titled “Rules and uncertainty”Use must for a required rule, should for a recommendation and can for a capability. State who enforces a requirement and what happens when it is not met. Avoid unsupported guarantees about isolation, delivery, freshness or recovery. Identify the specific missing information instead.
Keep three kinds of statement distinct: the documented contract, the inspected implementation and the result of an executed check. A coverage note belongs next to a claim when it materially limits that claim. General review metadata belongs in the page’s source details or evidence guidance.
Use descriptive link text that identifies the destination. Link when the target helps explain the current subject, not at every repetition of a term. Internal links explain the system’s relationships; revision-pinned source links establish provenance. Follow the linking rules.
Microsoft references
Section titled “Microsoft references”The language guidance follows Microsoft’s recommendations for clear word choice, consistent terminology and concise sentences in Use simple words, concise sentences. Heading conventions follow Headings. Link-text conventions follow URLs and web addresses. Toolora’s page ranges, topic register and evidence model are repository-specific.