I have spent a lot of years writing documentation, first for Aurelia 1 and more recently for Aurelia 2 at docs.aurelia.io. The scale taught me a few things that travel beyond any framework. Good docs are not marketing. Good docs help someone ship. That is the bar I write to.
Start with outcomes
Readers come for progress, not prose. I start each page with what this enables in one or two lines, then a minimal path to working code. Deep dives and reference tables can follow, but the first screen should move a reader forward. When the topic is new, I explain why it exists before how to use it.
Frameworks make this harder because they touch routing, data, rendering, testing, and the tool chain. People also arrive with very different backgrounds. The way through is a consistent page shape: short intro, quick start, deeper concepts, pitfalls, and links to related topics. It gives both the skimmer and the studier what they need.
Voice and consistency
Tone looks small until you hit page 200. I aim for clear, direct, and friendly. Active voice. Simple sentences. I write to one reader and use you. I avoid hype and I do not assume prior knowledge.
The hardest part is keeping the same voice across many pages and months. When I get tired, my sentences get fancy and mistakes creep in. A short style guide helps. So do a few live examples to copy. I also come back later with fresh eyes.
Consistency beats elegance. One name per concept. One preferred file structure. One way to show examples. If I find three ways to describe the same thing, I pick one and use it everywhere. For code, I keep samples minimal and complete so a reader can paste and run without guessing a missing import.
What changed from Aurelia 1 to 2
Writing for Aurelia 2 sharpened a few habits I started in Aurelia 1. Migration notes live close to the topic instead of in a silo. I show before and after side by side. I explain why a change happened, not just that it happened. I link to the new way as the default and keep the old way visible for people moving at a different pace. That balance keeps the site useful to both groups.
Make them findable
Search matters more than people think. Clear headings, predictable titles, and consistent names make the index useful. I avoid cute titles and pick the terms people already type into a search box. I also use the same example domain across a section so readers do not have to relearn context on every page.
Keep them honest at scale
Docs rot when examples are not run and links are not checked. I try to treat docs like code. Build them. Run the samples. Check links. Keep snippets close to real code when possible. When a page grows, I split it and add a hub page.
Typos and small grammar slips are inevitable at scale. Tools help but the community helps more. People find the rough edges fast. I take those reports as a gift because small fixes make the whole site feel cared for.
Review helps too. A second pair of eyes catches tone drift and blind spots. If a sentence makes someone stumble, I change the sentence.
A few tips that help me: start every page with the outcome, prefer task guides when readers are new, keep samples small and runnable, link to the next likely step, and keep a short style guide close so drift is easy to catch. When a feature changes, I update the example first, then the prose.
Helping people ship is the point. My time on the Aurelia docs sharpened that lesson, but the advice here works anywhere. If you write with care, keep your tone human, and let readers show you where to improve, your docs will pull their weight.