Technical Content Standards

A working editorial system for technical education — and a study of what happens to it when you move it to reference documentation.

Where this comes from

These standards were developed between 2025 and 2026 while building the technical content function at Shortcut, a mentorship platform for software engineers. They govern 47 courses across algorithms, DevOps, frontend, backend and machine learning, written by a team of subject-matter experts and supported by AI agents.

This repository is the English, domain-independent version of that system. The rules here are not aspirational — every one of them exists because something went wrong without it.

What is in here, and what it claims

The distinction matters, so it is stated up front rather than buried.

The standard itself — principles.md and the four documents that follow from it — describes educational content: courses, lessons, structured material a learner works through in order. That is where it was built, tested and revised over nine months.

adapting-to-documentation.md is a separate piece of work: a principle-by-principle translation of the same system into reference documentation, where the reader arrives from a search result, reads one page and leaves. It says which principles transfer unchanged, which need modification, and which do not apply at all — and it marks its own conclusions as reasoned rather than tested.

They are kept apart deliberately. A standard proven in one genre does not automatically hold in another, and presenting the translation as though it carried the same evidence would be dishonest about both.

Who this is for

• Writers and engineers producing technical content, who want a standard to work against
• Content leads who need to keep quality consistent across contributors who are experts in their subject but not trained writers
• Anyone introducing AI into a content workflow and discovering that "just use an LLM" produces content that reads well and teaches nothing

How to use it

Read principles.md first. It contains the reasoning; everything else is derived from it. A rule you apply without understanding its purpose becomes cargo cult, and cargo cult produces worse writing than no rules at all.

Then use the rest as reference:

Document	What it covers
principles.md	The reasoning: what teaching material is for, and how it fails
structure.md	How a lesson is built: openings, body, endings, practice
style.md	Voice, wording, and the constructions to avoid
code-examples.md	Rules for code in teaching material
review-checklist.md	What a reviewer checks, in order
working-with-ai.md	Prompts and constraints for drafting and reviewing with LLMs
adapting-to-documentation.md	The same principles, translated for reference documentation

Licence

CC BY 4.0 — use, adapt, and build on these with attribution.