I have spent more time than I care to admit writing technical documentation for Aurelia 2. The docs at docs.aurelia.io have been through countless revisions, rewrites, restructures, and moments where I stared at the screen wondering if I had forgotten how to form sentences.
Writing code is hard. Writing about code in a way that helps other people write code is harder. Nobody prepares you for this.
The first thing you learn is that you do not actually understand the thing you are documenting. You think you do. You have used it, you have built things with it, you can explain it to a colleague at your desk.
Then you sit down to write a page about it and realise you have been holding it together with vibes and muscle memory.
The act of writing forces clarity. If you cannot explain something simply, you do not understand it. I have had to go back to source code more times than I can count because my “understanding” turned out to be a house of cards that collapsed the moment I tried to write a coherent paragraph.
You also learn that there is no such thing as writing documentation once. You write it, ship it, and immediately someone finds the gap you did not see. Or the API changes. Or you read it six months later and wonder who let a confused raccoon near the keyboard.
Documentation is not a task you complete. It is a garden you tend. Stop tending and the weeds take over fast.
I have rewritten sections of the Aurelia 2 docs more times than some people have read them. Not because I am a perfectionist (okay, maybe a little) but because each rewrite teaches you something about how people actually learn.
The first draft is always written for yourself. It makes sense to you because you already know the answer. The second draft is where you start to see through someone else’s eyes. The third draft is where you finally kill your darlings and admit that your clever explanation was actually just confusing.
One of the hardest lessons was learning that completeness is not the goal. My early docs tried to explain everything. Every option, every edge case, every possible configuration. The result was dense walls of text that nobody read.
People do not come to docs to learn everything. They come to solve a specific problem and leave. The job is to get them in, give them what they need, and get them out. If they want to go deeper, let them. But the default path should be fast and practical.
I spent months structuring and restructuring the Aurelia docs. Should concepts come before tutorials? Should we lead with quick starts or deep dives? Should migration guides live with the features or in their own section?
There is no universally correct answer. Every choice has trade-offs. The best structure is the one that matches how your users think. And the only way to learn how your users think is to watch them struggle with the current structure and feel the pain yourself.
Consistency sounds boring until you are 200 pages in and realise you have been calling the same thing three different names. “Component” in one section, “custom element” in another, “element” in a third.
Readers do not know these are the same thing. They assume you are talking about different concepts and get confused. A style guide helps but only if you actually follow it. And following it requires discipline when you are tired and just want to ship the page.
Here is a confession: I have written documentation while not fully understanding the feature. Not intentionally, but it happens. You are on a deadline, the feature is new, and you do your best with what you know.
Then someone files an issue pointing out that your example does not work or your explanation is wrong. It stings. But it is also the process. Documentation is collaborative even when you are the only one writing it. The readers teach you as much as you teach them.
Code examples are their own special nightmare. They need to be short enough to understand at a glance but complete enough to actually run. They need to show the concept without getting lost in boilerplate. They need to stay current as the framework evolves.
I cannot count the number of times I have run a code sample from the docs only to find it broken because something changed three releases ago. Keeping examples alive is a full time job that nobody wants to do.
The emotional part is real too. You pour hours into a page, explaining something carefully, structuring it well, making it accessible. Then you check analytics and see that almost nobody reads past the first paragraph.
Or someone opens an issue saying the docs are bad and they cannot figure out the thing you spent a week explaining. It is easy to take it personally.
The trick is to treat every piece of negative feedback as a gift wrapped in frustration. They cared enough to tell you. Most people just leave and never come back.
I have also learned that perfect is the enemy of shipped. You can polish a page forever. At some point you have to accept that it is good enough and move on.
Someone will find something wrong. Someone will suggest an improvement. That is fine. Ship it, learn from the feedback, iterate. Documentation that exists and is mostly right beats documentation that lives forever in your drafts.
Writing for different skill levels is another puzzle I never fully solved. Beginners need hand holding. Experts need reference material and edge cases. Intermediates need something in between.
You cannot write one page that serves all three well. The best compromise I found was layered information: start simple, progressively reveal complexity, link to deeper dives. But even then, someone is always left behind or bored.
The tools matter less than you think. I have used wikis, markdown, custom sites, Notion, you name it. Good docs can be written anywhere. Bad docs can be written anywhere too. The tool does not save you from unclear thinking or inconsistent voice.
If I had to distill everything into one piece of advice, it would be this: write for someone who is stuck at 5pm on a Friday with a deadline.
They do not want to read your prose. They do not care about your architecture decisions. They want to copy something, paste it, and see it work. If your docs do that, they are doing their job. Everything else is a bonus.
The Aurelia 2 docs are better than they were. They are not perfect. They will never be perfect.
But every revision makes them a little more useful for the person who just needs to figure out how routing works or how to set up dependency injection. That is the whole game. One page at a time, one revision at a time, one reader helped at a time.
If you are thinking about writing documentation for your project, start. It will be bad at first. That is normal.
The only way to get good is to write a lot, get feedback, and rewrite. There is no shortcut. But when someone tells you the docs helped them ship something, it is worth every frustrating hour.