Writing technical content: articles, user docs. A task dreaded by so many people, especially those building software products. It’s easy to forget that the docs are just as important as your code.
Good documentation can mean the difference between average and great products.
For some years now, I have been involved in creating content for our blog, reviewing my author-colleagues work, writing user-guides, and feature descriptions. I have gathered many thoughts on both what you should do and what you shouldn’t. Inspired by the famous writing Good Product Manager/Bad Product Manager from Ben Horowitz, I structured my thoughts using the same paradigm.
Free yourself from yourself. Exactly – writing is a skill that almost anyone can learn and master. Of course, your writing is going to improve from one trial to the next. You’ll see that the good writer will always find ways to improve his writing skills and give his best in every piece of content. You will recognize a bad writer when you get half-done content and you hear “Well, I just left this part for the editor or the reviewer.”
Make time for writing. A good technical writer spends at least 1/5th of the time it took a developer to code the specific feature on writing its documentation. A bad technical writer will get it done twice as fast.
Do your research. You really need to own your subject AND your audience. So, a good writer would perform thorough research on the topic including reading what’s out there already. Identifying what is successful and what made that content successful. That way you start knowing what does your audience wants to read about. The bad technical writer skips this step because, of course, he already knows the topic by heart, and anyway “the research is a waste of time.”
Experiment. There is no way to replace this step – nobody knows if something that worked for an audience is going to work for yours. A good writer tries different writing styles and keeps experimenting. A bad writer will go with “his style” and “this is how he writes.”
Set the scene. A good technical writer assumes the reader is a first-time user and links to the related articles while keeping the focus on the topic. A bad technical writer assumes the reader already knows the application.
Review your content. A good technical writer asks for feedback on every material he works on. A bad technical writer seeks only praise and rejects most of the suggestions, he usually gets bored by the topic as soon as he finishes the materials.
The good technical writer understands the importance of editing. Those of you that tried to deliver content in a rush and by stumbling upon it sometime after publishing found out how different you would write the same content now. Well, folks, that’s editing’s power. Do not underestimate it! Leave your work untouched for at least overnight – and come back with fresh eyes (yours of somebody else’s) and admit that the article looks so much better after editing. A bad technical writer publishes the first version of his article.
Update your content. A good technical writer revisits old articles and refreshes them with new information. A bad technical writer focuses only on adding new content.
Eat your own dog food. A good technical writer uses his empathy and always plays the user role before writing a new article. A bad technical writer only uses internal docs and suppositions to describe a solution/feature.
Listen to your users. A good technical writer chooses his topics based on what his audience is interested to learn about. I have found it useful to spend time every week reading through user support tickets, forum threads, technical social media as StackOverflow or Reddit and use them as inspiration for improving articles. A bad technical writer gets his tasks only from the issue tracker.
Read for inspiration. A good technical writer schedules time for analyzing docs from other products, preferably those he admires, to sharpen his skills. A bad technical writer reads only social media feeds.
Answer to comments and questions. A good writer always welcomes comments and questions. And answers them promptly and respectfully. A bad technical writer gets it personally and looks for faults instead of opportunities.
Read it out loud and VERY slowly. Be critical over your every word. Good technical writers never skip this painful step. Bad technical writers defend every word by dismissal or find a thin excuse for why it is not worth paying attention.
Do you have any recommendations to add to this list? Leave me a comment.
Thanks, Cristina Constantinescu & Sorin Stefan for feedback on drafts of this.
Check out our latest product: Bytes Route.
It’s all you need to onboard your website visitors and help them discover your web app.