Documentation mode (instructional)

For content that helps a designer or developer make a decision or build correctly: component pages, guidelines, content policy, and accessibility guidance....

For content that helps a designer or developer make a decision or build correctly: component pages, guidelines, content policy, and accessibility guidance. Apply current MDS brand and content rules rather than treating selected component pages as fixed examples of good writing.

Register

  • Prescriptive but reasoned. State the rule, then say why it matters and where it applies.
  • Second person for the reader (“you”), “the user” for the person using the product, “people” only for broad human behaviour.
  • Imperative subsection headings that name the decision: “Choose the right fit”, “Keep the trigger visible”, “Match the field to the data”.
  • Calm and factual. No enthusiasm markers, no exclamation marks, no first-person team voice.
  • Vary the form to keep the effort of reading low. Use short bullets for parallel rules the reader will scan, and prose with a reason only where the reasoning changes the decision. Not every rule needs a “because”, and a page where every sentence has a condition and a reason is tiring to read.

Rules

  • Lead with the decision, not the background. The first sentence of a section should be the guidance.
  • Replace vague qualifiers (“appropriately”, “as needed”, “when relevant”) with a boundary the reader can act on. Never invent a threshold the source does not provide.
  • Prefer “Use X instead of Y when …” over “Do not use Y” so the reader gets a next action.
  • Use Do/Don’t pairs for consequential boundaries; a single example for a recognised pattern.
  • Link to shared policy rather than restating it.
  • Keep error, empty-state, and helper copy kind, plain, and specific (see /content/error-messages): name the problem and the recovery path, never blame the user.

Example

Choose the right fit

Use the medium fit for standard forms and the small fit only inside dense toolbars where vertical space is constrained. A larger fit does not increase emphasis; use variant and hierarchy for that instead.

Anti-patterns

  • Opening a section with history or motivation before the rule.
  • “It is important to note that…”, “In order to…”, and other filler openings.
  • Equal coverage of every property instead of weighting depth to the primary decision.
  • Marketing adjectives (“powerful”, “seamless”, “robust”) in instructional prose.
  • A heading that is a full sentence, followed by a first sentence that says the same thing.
  • Stating one decision in several sections instead of once and linking to it.
  • Sentences about the page itself: a preview of what a section covers, or a definition of an ordinary word.