Writing Better Documentation and Why Documentation Is Important
Is Documentation Worth The Time and Effort?
Some people find writing documentation to be very tedious and time-consuming. But the same applies to personal hygiene. It takes time and would we choose not do it, it would save us hours every week, yet it is necessary. Just like personal hygiene writing documentation takes time as well but it ultimately makes our lives better. Writing documentation isn’t more important than writing code and it’s not a waste of time. Documentation can even save you time and money. Having great onboarding docs for example, which will enable your new employee get a quick jump start without much help, are much more time and cost-effective than having one of your other employees take a few days off to train the new employee personally.
Why Documentation?
You may wonder why documentation is so important and the answer is pretty simple: If you want your projects to survive longer than your attention span, you need to document them. Even the most elegant code needs documentation. Documentation provides a framework for how to approach reading your code and people usually don’t want to have to read your code in order to figure out what it does.
How Do You Become A Good Writer?
But what’s the secret to becoming a great tech writer? Becoming a good writer takes a lot of time and practice and so Katie recommends writing fan fiction to practice writing and communication. If you write something fun you enjoy to practice this will help your technical writing skills, too. Just like you need to practice coding, you need to practice writing. If you’re experienced you write faster. You are able to see what the weak sections of your writing are. You are be able to communicate clearly. You are more confident. Or to say it in Katie’s words: “You have a certain number of crap words in you and you need to get them out. Practice!” It is advised to read what you want to write. If you want to write fan fiction, you should read fan fiction. If you want to write documentation, you should read documentation. If you want to write blog posts, you should read blog posts.
Organization and Perspective
One crucial part to being a good writer is organization. Before you start writing you should always create an outline. This will not only make the process of writing easier and more organized, it will also help avoid problems down the line. Fixing an issue in your outline is much easier than fixing an issue once you’ve already written whole sections. Additionally outlines will take pressure off your brain and allow you to switch between different sections. If you don’t feel like writing one section right now you can skip ahead to a different section and come back to the other section later.
Another crucial part to good writing is considering perspective. You need to choose which perspective you’re writing from before you start writing. You have to be aware of the assumptions you make about your audience. What do they know? What don’t they know? What do they need to know? Think of your audience constantly. Perspective is about manipulating the reader into feeling and knowing exactly what you want when you want it for the biggest impact. In technical writing you’re revealing information for example. As you write you need to keep checking yourself and consider the following:
-
Have you explained everything according to your reader’s knowledge or did you leave out crucial parts?
-
Are you tossing too much information at your reader at once?
-
Do you call attention to things which are important?
Sometimes we leave out steps because they seem obvious to us but they might not be obvious to our reader. It is therefore important not to leave out the hard parts, caveats, or things you’re not familiar with. You also should avoid to just talk about the cool things your app or module can do and leave out crucial parts like setup or system requirements.
Additionally, you should keep your language simple. A lot of newspapers are written according to sixth grade writing standards for a reason. Newspapers want their readers to be able to consume a lot of information quickly. You want to achieve the same for your readers as you will be giving throwing a lot of information at them and want them to understand it quickly as well. Therefore keep it simple. Don’t use a lot of big and fancy words or complex sentence structure. It isn’t necessary.
Writing Resources
Katie recommends the following writing resources:
-
Podcasts: Writing Excuses, I’d Rather Be Writing
-
Workshops: How to Write a Novel by edX
Other great ideas are to join a writer’s group in your area or online, to participate in the NaNoWriMo, or to establish a tech writing group at your company.
Katie’s PyTennessee keynote wasn’t recorded but you can watch a recorded version of the same talk she gave at PyCon Australia here