/iso-24495-5

name: iso-24495-5
description: Provisional sector-specific Plain Language standard for document design (based on ISO/WD 24495-5, under development). Applied when structuring complex documents so readers can find and navigate content through layout, visual hierarchy, and navigation aids.
metadata:
  version: "0.7.0"
  iso-standard: "ISO/WD 24495-5"
  iso-status: "working-draft"

ISO/WD 24495-5 - Plain Language (Document Design) [PROVISIONAL DRAFT]

> **Provisional status:** ISO 24495-5 is a Working Draft (ISO/WD 24495-5) and is not yet published. This skill is original guidance based on the draft's public scope and established information design practice. It does not reproduce ISO text. Expect revision when the standard is published.

> **Sources:** several rules here paraphrase the Document design pattern library, version 0.6, June 2025. That library is by Waller, van der Waarde, Schriver, Slabbert, Cheek and Linsky, for the International Plain Language Federation. The wording in this skill is ours, and no substantial wording is copied from it. Read the [Document design pattern library at the International Plain Language Federation](https://www.iplfederation.org/wp-content/uploads/2025/06/ISOpatternlibrary06.pdf) for the original.

Extends ISO 24495-1:2023 for the structural design of complex documents: reports, specifications, guides, contracts presented as documents, and long-form technical or health information. Design works together with linguistic cues to help readers find and navigate a document's structure and content.

**Design for readers who are not looking at the page.** The intended readers include everyone who uses the document. Some see it, some hear it through a screen reader, and some read it by touch.

A listener has no visual hierarchy. Their structure is the heading tree, the link text and the reading order. Every rule below is written to hold when the document is heard.

Scope & Execution Boundaries

1. **Thinking Block Exemption:**

• Internal layout planning and structural reasoning within thinking blocks (the `thought` and `thinking` tags) are **100% exempt** from these constraints.
• Plan freely within thinking blocks. Apply document design rules strictly to final user-facing documents.

2. **Design as Engineering, Not Decoration:**

• Base every design decision on a documented reader need (finding, navigating, comparing, acting). Never add visual elements for aesthetic effect alone.

3. **Content Primacy:**

• Document design must **never** cut or distort content to fit a layout. Accuracy and completeness supersede visual tidiness.

---

Required Templates

Read the matching template before writing any of these document types:

• **Architecture decision record (ADR):** Read the template file at `assets/adr-template.md`.
• **Runbook:** Read the template file at `assets/runbook-template.md`.
• **Design document:** Read the template file at `assets/design-doc-template.md`.

Restructure an Existing Document

When asked to restructure an existing document:

1. Identify the reader tasks, current hierarchy, and navigation needs. 2. Preserve every prose passage and content item. 3. Change headings, list types, table structure and visual formatting. You may also move a whole sentence or block, unchanged. Move it only where its dependencies, its order against neighbouring steps, and the claim it qualifies all survive. 4. Build the opening block, the overview and the signposts from sentences the document already holds, or from wording the author gives you in the request. Promote a sentence only when it states the field directly, and stays both true and complete enough for that field once away from the paragraph it came from. Where the author's wording contradicts the document, promote neither and report the mismatch. 5. Where nothing serves, leave a marked slot such as `[Author needed: purpose]` and report it as a gap. This covers the overview's content as much as its label. Never supply the missing wording yourself. 6. Check the result against the hierarchy, navigation, structure, and signalling rules below.

Do not rewrite prose, change tone, or remove content. Those changes belong to Parts 1 to 3, and so does rewording a sentence to make it fit a slot. A wrong purpose sends a reader confidently in the wrong direction, which is worse than no purpose at all.

---

Quantitative Rules & Hard Constraints (User-Facing Documents)

1. **Visual Hierarchy Limits:**

• Use at most **3 heading levels** below the document title. Flatten deeper nesting into lists or tables.
• Make headings state the section's message or task, not just its topic (*"Install the dependencies"* rather than *"Dependencies"*).
• Two exceptions here, one override in rule 8, and no others. A document type with a published structure keeps that structure's section names, as a decision record keeps Context and Decision.
• A reference section a reader jumps to by subject keeps the subject as its name, as a specification keeps Data Model. A section read in sequence gets a message or a task.
• Reject a heading that jokes, puns or plays with words. Reject one built on a term the document has not yet explained, because a reader skimming meets the heading first.

2. **Navigation Aids:**

• Add a table of contents or link list to any document with **6 or more sections**.
• Keep heading wording identical between the table of contents and the section it points to.
• Number headings when a reader must cite one by its identifier, and never below the depth limit above.

3. **Chunking & White Space:**

• Present one idea per visual chunk (paragraph, list, table, or callout). Separate chunks with blank lines.
• Never run two unrelated topics together in one paragraph or one table.

4. **Choosing the Right Structure:**

• **Comparisons:** Use a table when readers must compare 2 or more items across shared attributes. Name the narrowest presentation the table must surv