Documentation · Documentation version 1.0
Technical Content Quality Standard
The editorial standard used for guides, documentation, and templates on this site — written to be copied and adapted.
Written by Aaron Grainger
Independent Content Strategist & Product-Marketing Writer · Published Mar 2, 2026
- Primary audience
- Developer advocates and technical writers
- Also useful for
- Growth and content leaders at developer-tool companies
- Tone
- Authoritative
- Reading time
- 2 min
- Published
- Mar 2, 2026
In short
This is the working quality standard for technical content: what a page must establish before publication, how code examples are labelled and verified, how uncertainty is expressed, and what is never published. It is an internal-style document, published openly so it can be reused.
Scope
Applies to guides, tutorials, reference documentation, templates, comparison pages, and field notes. It does not apply to changelogs or release notes, which have their own constraints.
Requirements
| Dimension | Requirement | How it is checked |
|---|---|---|
| Accuracy | Every factual claim is either verifiable or labelled as a design opinion | Reviewer opens the source or the label |
| Audience fit | One named primary audience; depth matches it | Badge on the page matches the vocabulary used |
| Task completion | A reader can finish the stated job without leaving for a second source | Walk the steps as written |
| Scannability | Headings describe content, not clever phrases | Read headings alone; the shape should be clear |
| Code | Labelled runnable or illustrative; illustrative code uses example.com | Label present on every block |
| Diagrams | Carry information not already in the prose | Remove it — does the page lose anything? |
| Versioning | Version and published date visible and editable in data | Present in the page metadata |
| Source links | External claims link to the source; internal concepts link to their definition | Link check |
| Disclosure | Independent-project disclosure present on content pages | Footer module present |
| Accessibility | Semantic headings, alt text, contrast, keyboard-reachable controls | Manual pass |
| Discoverability | Title and description answer a question someone would ask | Read them out of context |
| Extractability | Direct answer near the top; definitions stated plainly | First 80 words stand alone |
Code example rules
Before a code block ships
- Labelled either "runnable" with its versions, or "illustrative pseudocode"
- Uses example.com and obviously fictional identifiers
- No credentials, tokens, or internal hostnames
- Short enough to read in one screen; longer examples are split
- Comments explain decisions, not syntax
- If runnable: executed once, output pasted or described accurately
Handling uncertainty
Three labels, used consistently: tested practice (someone did it and reports the result), conceptual example (a design that is reasonable and unverified), open question (nobody involved knows yet). Mixing the three without labels is the most common way technical content becomes untrustworthy.
Updates and deprecation
- 01Review when the underlying concept, tool behaviour, or recommended practice changes — not on a calendar.
- 02Material changes get a version entry with a one-line note.
- 03Superseded pages link forward and stay reachable; broken URLs are worse than dated content.
- 04Withdraw rather than quietly edit when the original advice was wrong, and say so on the page.
Never publish
- Invented metrics, benchmarks, customer counts, or performance results.
- Testimonials, case studies, or partnerships that do not exist.
- Competitor claims that cannot be sourced, or comparisons written to flatter.
- Rankings presented as objective when the criteria were chosen to produce them.
- Screenshots of interfaces that have never existed, presented as product.
- Filler openings: the pace of change, the age of AI, the unlocking of potential.
Practical takeaway
- State the audience and the job before writing the first heading.
- Code is pseudocode until someone has run it; label it either way.
- Uncertainty is content, not a gap to be smoothed over.
- A page with nothing to say about trade-offs is not finished.
Related content
Strategic guide · 4 min
How to Measure AI-Answer Visibility
A practical, skeptical framework for tracking whether your product appears in AI-generated answers.
Foundational guide · 3 min
The Anti-Hype Guide to Web-Enabled AI Products
What these systems actually do well, and where the claims outrun the engineering.
Field note · 2 min
Technical Content Is a Product Surface, Not a Distribution Channel
Guides, docs, and templates are where evaluation and implementation actually happen.
Research note · 2 min
A Taxonomy of Web-Data Failure Modes
Debugging a web-data pipeline is easier when failures have names. This note proposes a working taxonomy across five layers — access, retrieval, normalization, extraction, and inter
Version history
Current: 1.0 · Documentation version
- 1.0Mar 2, 2026First published.
Was this useful?
Sourceframe is an independent product concept created for research, product-design, and technical-content exploration. It is not an operating company, and nothing here describes a live commercial service. All examples, schemas, and code are illustrative unless a page says otherwise. No client data, customer outcomes, performance results, or partnerships are described anywhere on this site.