A reading guide that tells somebody which pages they need

Why this block is harder than it looks

Long documents are read by several kinds of reader who each need a different part, and without a guide every one of them reads the front matter and gives up. The block is short, so the difficulty is not layout mechanics but restraint: the temptation is to summarise the document, which produces a second document nobody asked for. What earns its place is routing, not summary, and routing needs page numbers, which means the same target-counter machinery the contents page uses.

The decisions that make it work

Reasons rather than a description of the code. Each of these is a choice that has a wrong answer, and the wrong answer is usually the default.

• Route rather than summarise. If you are in a hurry, read section 3 is useful; a paragraph about what section 3 contains is not.
• Address the reader types explicitly by name, since a person recognises their own role faster than they recognise a topic.
• Resolve the page numbers with target-counter, the same as a contents page, so the routing does not go stale.
• Keep it to four or five lines. A reading guide longer than the contents page is a document about a document.
• Place it after the contents, not before. A reader needs to know the shape before being told which part to read.
• Keep it together with break-inside: avoid, and never let it be the last thing on a page with its routing on the next.

The fragment

Markup and the CSS it needs, and nothing else. It expects a document that already has a page rule and a base stylesheet, so paste it into one rather than opening it on its own.

<section class="reading-guide">
  <h2>How to read this document</h2>
  <ul>
    <li><b>If you commissioned the survey:</b> the findings and the
      recommendations, <a href="#findings">page</a>.</li>
    <li><b>If you are quoting for the work:</b> the schedule of defects and the
      access notes, <a href="#schedule">page</a>.</li>
    <li><b>If you are checking compliance:</b> the method and the limitations,
      <a href="#method">page</a>.</li>
  </ul>
</section>

<style>
  .reading-guide {
    break-inside: avoid;
    margin: 14pt 0;
    padding: 8pt 0;
    border-top: 0.5pt solid #ccc;
    border-bottom: 0.5pt solid #ccc;
  }
  .reading-guide h2 {
    break-after: avoid;
    margin: 0 0 5pt;
    font-size: 10pt;
  }
  .reading-guide ul { margin: 0; padding-left: 14pt; font-size: 9pt; }
  .reading-guide li { margin-bottom: 3pt; line-height: 1.45; }
  .reading-guide a { text-decoration: none; color: inherit; }
  .reading-guide a::after {
    content: " " target-counter(attr(href url), page);
    font-variant-numeric: tabular-nums;
    font-weight: 700;
  }
</style>

What breaks when it is built the obvious way

Writing it as an executive summary. A summary tells the reader what the document says, which means they can stop reading, and the parts they needed were the parts a summary leaves out. Routing sends them to the right pages; summarising replaces them.

How to prove it survived pagination

Give the document to three people with three different reasons for having it and time how long each takes to reach the part they need. If any of them reads past the guide without stopping, their role is not named in it.

Where it sits in a finished document

This page is one block. The document it belongs to has a page rule, a base stylesheet, a header and everything else around it, and repeating all of that here would make thirty pages that say the same thing. The multi-page report template is a complete file with this block already in it, so take that and change the fragment rather than assembling one from parts. The property doing most of the work here is covered on its own page, with the support caveats that belong there rather than here.

Frequently asked

Other parts of a document

The blocks that sit next to this one, and one from the next group along so you are not sealed inside a single kind of problem.