Becoming an Excellent at documentation: A Non-Writer's Guide

Hi, I am Tshepiso. This post is my newsletter EverydayDev .
Each issue contains a summary of a talk I have watched from a tech conference.

---

Programming isn’t about what you know; it’s about what you can figure out.

---

Hey digital Pals! 🍁

This week I have serious back to school FOMO! I carry the self-taught developer badge with honour but I can’t deny that I would like to acquire deeper knowledge to enhance my technical skills. I am highly considering taking some introductory courses that I can manage with full-time employment.

My requirements is that it should be part-time and remote. So far the courses that I have found that fit into that box are Introduction to Artificial Intelligence and Robotics for all . Let me know what you think in the comments.

The world is my oyster!

This week’s talk is Stop writing docs, start helping by Sarah Rainsberger. Let’s get into it.

---

The art of writing Docs

Up until perhaps 4 months ago, I avoided reading docs. This is not an understatement. If I ever searched for something and MDN was on the results list I would pick something else. I preferred to get the answer from a blog or tech article.1 I found most of it easier to follow and more personal. Today I am proud that I can follow an MDN article and maybe I needed to evolve my technical understanding to make sense of them and other technical docs, however, is it possible that some docs are just not well written?

Screenshot from a Reddit forum post. Read the post here

Sarah starts the talk with the advice we have all heard but ignore and that is we should not strive for our docs to be perfect. Whether your doc is the changeLog, ReadMe, website or the actual code, it will never be perfect so you can take that pressure of.

Start by figuring out what the purpose of your doc is. Internal docs are for cross team collaboration and onboarding. External docs are for people to understand, evaluate and use your project. Open-source docs are to help people contribute to your project. Ideally you want people getting out of your docs and back to using your project.

“Don’t strive for your docs to be good, strive for them to be helpful.

When we focus on making the doc helpful we turn the activity from being about our self-validation (am I good enough to write this doc) to the needs of the users. This is how you turn technical documentation from being a writing task and instead being a helpful task:

( Sarah’s points echo those in Mason Egger’s talk, Write docs devs love. In the talk Mason goes through ten tips to have good docs. I have added some of those points here.)

• Be clear and correct. Don’t have misleading , outdated and unhelpful information. If it is not clear- delete it.

• As a helper, there’s no need to add jokes , stories or make the doc “entertaining”. This will also free you from having to make sure your grammar and punctuations are perfect.

  

• Use you/your so that the emphasise is on the user.

• Make it clear to the reader what is optional and what is mandatory. Using “should” makes things ambiguous.

• Make your docs navigable. Information should be where your reader expects it to be. If it means having one long README page with table of contents then go for it.

• Keep the language simple. Not everyone is a native speaker of the language which you are writing in. Use tools like Hemingway editor to check the readability level of your writing.

• Include everything. Imports as well!

• With the exception of internal docs, limit the use of technical jargon. Explain your abbreviations and don’t make people feel stupid.

Conclusions:

Not only will this 20 minute ViteConf talk give anyone the confidence and the assurance that they can write helpful technical documentation. But, it will also provide readers with the tools to identify good docs from bad ones and not blame themselves.

---

Behind the scenes

• 

• One of my inspirations for watching more talks comes from an event my colleagues host every Thursday where we have fika and watch a talk briefly together and discuss it. It’s a very low-effort knowledge sharing activity with sweet rewards!