Obscyra Digital Obscyra DIGITAL
Shelves of neutral-bound policy volumes above a row of quiet reading desks in Obscyra Digital's documentation room

Documentation standards — Obscyra Digital

Standards and accessibility for every document

Applies to
Every published policy and guide page
Reference
W3C Web Content Accessibility Guidelines
Review
Checked before publication, every time

This page sets out the writing, structure, and accessibility rules that every Obscyra Digital document must meet. The goal is consistency: a reader who learns how one page works should be able to rely on the same structure on the next one.

Read the standards How the review process works

On this page

The rules we hold every document to

Nine standards cover everything a reader meets on a page: why we standardize at all, how we write, how headings are ordered, how a page is laid out for scanning, how links read, what readability promises we keep, how terms stay consistent, how long a section should be, and what happens before publication. Each one below states the rule and what it means in practice.

Why we standardize

Cost removed
Relearning the layout on every page
Held constant
Headings, sentence length, terminology
Source
W3C Web Content Accessibility Guidelines

Why we standardize

When every page is structured differently, readers have to relearn the layout each time. Standardizing headings, sentence length, and terminology removes that cost. The W3C Web Content Accessibility Guidelines shape many of these decisions, because a structure that is readable and navigable by assistive technology tends to be readable by everyone.

That last point is the practical argument. A screen reader user hears the page in a linear order that the markup decides. If the heading levels are inconsistent or a section starts with a visual pose rather than a statement, the same defect that annoys a sighted reader blocks a reader who cannot see the page at all. Fixing structure for accessibility fixes structure for everyone else.

We also treat standards as a review contract. A document is not assessed on taste or tone preference; it is measured against the checks named on this page, and the reviewer has to be able to point at the specific rule a draft breaks. That keeps the conversation about the reader rather than about the writer.

Plain language rules

Plain language rules

We write in short sentences and avoid stacked clauses. A sentence that needs a second read to parse is rewritten. We define a term the first time it appears and then use it consistently, rather than swapping in synonyms that force the reader to check whether two words mean the same thing.

Sentence length

One idea per sentence

Two clauses joined by "and" usually mean the writer was unsure which half mattered. We split them and let the reader decide.

Word choice

Common word first

If a plain word carries the meaning, we use it. A formal term stays only when a rule or a definition depends on that exact phrase.

Definitions

Define it once

The definition sits at first use, in the same sentence or the one after it. Later sections reuse the term without re-explaining it.

These three rules cause most of the rewriting in review. They are also the cheapest to check, which is why they are listed before the structural standards that follow.

Structure and headings

Headings follow a fixed order so a reader can jump by level. The main heading states the document's subject, section headings state the job of each section, and subheadings carry detail. Heading text is specific rather than generic, which means a reader scanning only the headings can still follow the argument.

A reader's hands turning pages in a large-print reference book at a plain desk

The order we keep

  • Main heading

    Names the subject of the document. One per page, and it never restates the site name.

  • Section headings

    Describe the job of the section. A heading that could sit on any page gets rewritten.

  • Subheadings

    Carry detail under a section and appear only when there is a real second level to hold.

Levels are never skipped to make a heading look smaller. If a section needs a lesser rank, the content is usually a list item rather than a heading.

Scannability by design

Scannability by design

Research on readability and cognitive load, including the work published by the Nielsen Norman Group, supports layouts that let readers scan rather than read every word. We apply that by keeping paragraphs short, using lists where a list is the honest form, and placing the most important rule near the top of its section.

A list appears when the items are genuinely parallel: steps in a process, conditions for an exception, the fields a form requires. Prose appears when the argument has a direction. Turning a sequence of reasoning into bullets hides the reasoning, so we do not do it.

Rule placement

A reader who stops after the first screen of a policy page should already know the rule the page exists to state.

How a page is read on a phone guides the layout as much as a desk. If a rule only becomes clear in the third paragraph of a section, it moves up.

Publication condition

Meeting these standards is a condition of publication, not an aspiration.

Every rule on this page is checked before a document goes live. When a draft fails a check, it returns to the author with the specific rule named, so the fix is a known task rather than a matter of taste.

See the pre-publication checks

Link text and navigation

Link text describes its destination rather than saying "click here." A reader using a screen reader may navigate by links alone, so a link that reads only as "click here" is unusable. Navigation within a long page uses a table of contents so readers can move to a section without scrolling.

Where this shows up

Cross-references between a policy page and its guide, the table of contents on a long rule page, and every link out to a related document.

An open reference binder beside closed policy volumes on a documentation desk

Accepted

Link text names the document it opens, such as the governance review page, so the destination is clear before the click.

Returned

Link text that names the action instead of the destination goes back to the author and is rewritten before the page is reviewed again.

Contrast and readability commitments

Accessible documents need readable structure and navigable headings, and the same principle extends to how content is presented. We keep the content itself free of decorative noise, avoid text that depends on meaning carried only by position, and keep headings descriptive. The USWDS documentation page pattern is a useful model here: precise headlines, concise copy, and a layout meant for reference rather than promotion.

Position never carries meaning on its own. If a rule applies only to one group of readers, the text says which group. A note placed beside a table without a label would leave an assistive technology reader with no way to attach it to the right row, so notes are written as sentences instead of as floating remarks.

Structure

Headings, lists, and tables carry the hierarchy so a reader can move by landmarks.

Presentation

Decorative elements stay out of the reading path and never interrupt a rule mid-sentence.

Reference pattern

Precise headlines and concise copy, shaped for someone looking something up rather than browsing.

Terminology and consistency

Terms are defined once and reused. Where a term has a specific legal meaning, we use that meaning and say so. Consistency is not pedantry; a reader who sees the same concept called three different things assumes they are three different rules.

A shared word list keeps this from drifting as documents are revised by different authors. When a new term enters the list, the page that introduces it explains it in place, and later pages link back rather than restating the definition in their own words.

If a reader has to check whether two words mean the same thing, the document has already failed the standard, regardless of how well it reads line by line.

Length and depth

A section should be as long as its job requires and no longer. Policy pages state rules; separate guides carry extended explanation. When we are tempted to explain everything on one page, we split it: the policy keeps the rule, and the guide carries the reasoning. This matches how large documentation systems, such as GitHub Docs and Stripe Docs, keep individual topics modular and searchable.

Policy page

States the rule, its scope, and where an exception can be requested. Stays short so the rule is easy to find.

Guide page

Carries the reasoning, examples, and edge cases, and links back to the policy rule it explains.

Before a document is published

Compliance checks before publication

Before a document is published, it is checked against these standards: heading order, sentence length, term consistency, link text, and whether the table of contents matches the actual sections. A document that fails a check is returned to review. Meeting the standard is a condition of publication, not an aspiration.

  • [ok] Heading order matches the fixed sequence and no level is skipped between the main heading and a subheading.
  • [hold] A sentence runs long or a clause needs a second read. The sentence is split and the section is rechecked before it moves on.
  • [hold] A term appears under two different names, or a defined term is redefined later. The shared word list settles which one stays.
  • [warn] Link text describes an action instead of its destination. The link cannot ship until it names the document it opens.
  • [hold] The table of contents and the live sections disagree after an edit. The contents list is regenerated from the page itself.
  • [ok] The wording is consistent throughout and the standard holds.

Checks run against the draft, not against a description of the draft. A reviewer opens the page, reads it at the width a visitor will read it, and records the result on the review page before publication.

Questions we get in review

Standards questions, answered

These two come up most often from authors preparing a draft. More answers sit on the frequently asked questions page.

Read the frequently asked questions
What accessibility standard do these pages follow?

We align our structure with the W3C Web Content Accessibility Guidelines, focusing on readable structure, navigable headings, and clear link text.

Why split a policy from its explanation?

The policy page states the rule so readers can find it fast. Extended reasoning lives on a separate guide, which keeps the rule page scannable.

Does the standard apply to guides as well as policy pages?

Yes. Guides carry longer explanations, so they meet the same heading order, plain-language, and link-text rules as a rule page. The difference is depth, not the standard.

What happens when a draft fails a check?

It returns to the author with the rule named, so the correction is a specific edit. The page is not published until the open checks are resolved and the review record is complete.

Where to go next

Keep reading, or ask us directly

The governance page explains who reviews a document and how an exception is requested. The documentation library holds the published pages these standards govern. If a rule here is unclear or your draft seems to sit outside it, write to the documentation team and we will answer with the specific rule that applies.

Read the Governance and Review Process Open the Documentation Library

Documentation team

Email
[email protected]
Phone
+1-202-478-1904
Hours
Monday to Friday, 9:00 AM – 6:00 PM Eastern Time
Office
1201 Market Street, Suite 1400, Philadelphia, PA 19107, United States
Contact the documentation team