My top 5 tips for writing good technical documentation
As a Software Developer working on different types of projects, I tend to forget what I previously did. I even sometimes forget the tasks I’ve worked before in the same project. This is where logging down the essential information help.
Having a document even roughly drafted, makes it much easier, when I later have something to communicate or present to other colleagues. I don’t need to try to remember the particular details, look at the commits or go read in the codes once again.
So in this post, I share my best tips on how I usually pen down technical documents.
Separate writing and editing
If you try to do both, the task will seem too hard. Writing is more of a creative activity. Editing is more logical. These types of activities occur differently in the brain. By mixing both, you’ll be taking more time, making things less creative and harder for you.
Your first draft should only be dumping everything you can think of irrespective of order, structure and mannerism. Don’t think when you write (don’t think more that you should). Just aim to share what has been done and put it on the screen. The editing process will take a lot of time with multiple iterations.
Another good tip is to write as if you’re explaining to someone. Then when you edit — you refine, you cut out things — to make it more concise. I usually edit my documents in the span of multiple days when my brain is fresher.
Bonus: don’t use editing tools such as Grammarly when writing your first draft.
Communicating your work
I would argue documenting your work and doing the actual work are both as important. Of course there is no documentation without work.
I remember few years back in one of my previous jobs, I worked my socks off to complete my tasks. However, on doing that, at the end of the day, I barely had any mental strength left to update my tasks, the status and a quick description.
I didn’t also prepare a documentation of what I was doing. Some time later, even though, I did my work, which eventually went into production, middle management was convinced I didn’t do the work well or at all. Yet, there I was, present in the office everyday, working hard on every task I was assigned, present in the daily standups.
The only thing I struggled with was updating the status of my tasks on the task management tool. From then on, in my next roles, I made this a priority. This will reduce your productivity flow overall, but make the expectations clear that you’re also documenting the whole flow.
Furthermore, only doing the work won’t give the impression that you’re working because others can’t really see what you do, especially given the subject depth. Documenting the work and explaining it to others — even briefly — will give the best impression that you’re progressing — even if you’re stuck and being slow.
The nature of developers’ work and creative activities in general, is that our requirements constantly evolves. Imagine you work on a new feature and you’ve completed it. Then two weeks later, the requirement changes. You complete that as well. So in other people’s mind, especially non technical one, they might not possibly know the extend of the work you did, especially in the first iteration.
For technical colleagues, explaining to them even briefly, makes your work more visible, as a result, you become more visible. This document or task comments will help others later.
Outlining vs initial draft
I’ve found a mix is most effective for me. The brain works best when brainstorming ideas without initially taking structure into context. It usually operates without order, associating one thing to another. Think of mind maps. It just connects one thing to another.
If you’re going to begin with forcing a structure with your first draft, you might encounter the writer’s block.
Use images as often as possible. A picture means 1000 words. This is also more productive as you don’t need to always describe the context fully.
I usually use different editing tools depending on the nature of work, for example, notion for my blog posts so that I can edit the content on another computer. For my work, I like using Microsoft Word as it supports images well right of the box. I also use Typora for general drafts.
Using a good editing tool carries plenty of benefits such as:
- grammar errors highlight
- minimal interface to decrease distractions
- sleek UI with beautiful typography
Originally published at http://abdallahyashir.com on September 17, 2021.