#3usefulthings — #6— About documentation: catch zen of writing and understand the virtue of simplicity
#3usefulthings is a series of small blog posts with short overviews of some interesting and useful facts. Previous issues: 1, 2, 3, 4, 5.
It doesn’t matter do you write documentation about your product or not, you should write it. And here’s my favorite picture on this topic:
Writing documentation (internal or external) helps other people to understand how to interact with results of your work and reduce the bus factor. It’s easier to say than to do, as writing a good piece of documentation requires a lot of time and cognitive efforts. But the only way to learn how to do something well is to practice it, again and again. Small steps are better than nothing.
1. How to write software documentation in the right way. A great article from Divio about different types of software documentation.
It’s important to distinguish the different types of documentation and address the specific needs for each of them.
- A bad or missing tutorial will prevent your project from acquiring new users. A good tutorial allows the newcomer to get started.
- A how-to guide must address a specific question or problem: How do I …?
- In reference guides, structure, tone, format must all be consistent.
- Explanations are the place for background and context.
2. 600+ resources for technical documentation, all in one place. A huge collection at DocToolHub of useful links divided by categories: analytics, blogs, API, audience analysis etc.
I haven’t heard about the DocOps before, this term refers to “that takes on the challenge of applying Agile and DevOps principles to developing and managing technical documentation”.
One more discovery: Ray Bradbury wrote a book about writing: Zen in the art of writing. I read/listened to a bunch of his stories and novels and can say it’s one of my favorite writers in terms of rich vocabulary and endless fantasy. Also, I heard that he hated computers and wrote his books on a typewriter. It’s very interesting what such a prolific writer thought about the process of writing.
3. Tackle technical debt in knowledge management. One of the main pieces of advice in the article: start by documenting stakeholders in your knowledge management and customer self-service processes. Bring those people together and make an inventory of the areas heavy with technical debt.
Also, simplify as much as you can: the words, navigation through your documentation, layouts, and style.
Viva la simplicity✌
Don’t miss a chance to write a piece of documentation today.
