Background#
Recently, I have been thinking about how to make technical documentation better.
Two recent events have prompted me to start thinking:
- I watched Sarah Rainsberger's presentation "Stop writing docs; Start helping" at ViteConf.
- A documentation PR for the sync-to-xlog plugin.
Let me explain each one.
Documentation is meant to help people#
Sarah Rainsberger is the documentation lead at Astro, and this was her talk at ViteConf2023. I have shared the video on Bilibili, which you can watch here: # Astro documentation lead shares what makes good technical documentation and how to improve
Internal link: [[stop writing docs start helping]]
She gave a very classic example:
Source here
The image shows an installation guide. This example resonated with many people. The original technical documentation was very good, as it motivated readers and explained the author's thoughts. The improvement only required one sentence and a few words.
At that moment, what the reader needed was help on how to install, and simply telling them clearly and explicitly would suffice.
Documentation PR#
Please click here to view the PR
My thoughts:
- Be bold and use H1.
- Differentiate the installation steps. Add annotations, highlight and use arrows in the screenshot, it's not against the law.
- Reduce unnecessary words and describe facts in a more neutral, faithful, and calm manner.
- Keep reading and writing more.
Documentation can go from nothing to something, and from something to better.
When writing future documentation, I will pay attention and strive to do better.
The unified theory of documentation mentioned seems interesting, maybe it can be translated.