Technical Writing – It's Just Programming in English (*)

(* Other similar languages are available.)

Many programmers either struggle with or are uncomfortable with writing documentation and reports. For those of us in the British education system, I think the cause of this is likely to be the English exams we had to pass at school. These were aimed at one day turning us into Nobel Prize winning literarists rather than documentation writers.

To write "I was happy" in a British English exam would give you no marks. To write "I was very happy" probably wouldn't either. "I was deliriously happy" might get a mark, but you'd have to write something like "It was with cascading waves of joy that the happiness swelled within me" to get good marks.

In my opinion, the latter is not only unnecessary for software documentation (and business writing in general), but it is actually detrimental. You don't need an emotional response to software documentation. If the documentation brings you to tears, or even has too many jokes, it is unnecessarily taking up brain cycles that could be used to understand the matter at hand. It's like writing inefficient code. For software documentation, the equivalent of "I was happy" is not only sufficient, it is likely to be optimal.

Similarly, "I walked to the door. I opened the door. I walked to the table. I sat down," will not get you a pass in an English exam but does the job for technical writing.

Programmers are usually high achievers in other subjects, such as maths and science, so the lack of success in English really pushes them away from ever wanting to write English ever, ever again.

But, as I've said, the problem isn't that programmers can't write English, it's that the exams are targeting an unhelpful concept of what it means to write English.

In fact, programmers already have all the skills required to write good documentation and reports. Programming is the exercise of generating instructions to be read by a CPU. Writing technical documentation is the exercise of writing instructions to be read by a human. It's the same process, just a different programming language for a different target "machine".

Let's look at the steps.

Requirements capture: Before writing code it's a good idea to step back and list the requirements the software has to meet. Same with documentation and reports. Get a pen and paper or blank word processor document and start jotting down ideas. Mind maps are also a good idea.

Kanban (or similar): Write your requirements on post-its (I use the small 38 x 51 mm ones – also ideal as bookmarks!) and stick them on a board (I have an A4 sized piece of MDF.). Then reorder your post-its so they form a logical order for a document. When the item has been written up in your document to your satisfaction, strike through the text on the post-it (but leave the post-it on the board).

Sprint Planning: Staying focused while writing documentation can be a challenge for many. It's very tempting to just quickly check Twitter or Instagram or Discord while doing work. Sprint planning offers some insights on how to deal with this. At the core of sprint planning is making a commitment to do a certain amount of work in a certain amount of time. Similar commitments can be made while writing documentation. In the Pomodoro Technique [Pomodoro] you commit to working on a task for a period of time in the order of half an hour. You start a timer and until the timer goes off you commit to not being distracted from your task in any way. Naturally, if the timer goes off and you're in the zone, you can carry on. Otherwise you can have a small break and then make another half hour commitment.

Functional decomposition: Look at your post-its and break them down into smaller parts, as if you are writing functions within code. Decompose those functions into more functions. This ultimately maps to paragraphs in your document. The first paragraph might say you need to do A, B and C. You then have separate paragraphs for describing each of A, B and C. As with functions, many short paragraphs is better than a few long ones.

Naming: In code we name functions. We often group functions together into classes. And we can group classes into namespaces. If we're saying paragraphs in documents are akin to functions, then we group paragraphs into sections (classes) and sections into chapters (namespaces). In other words, all stuff we do every day as a programmer. Unless it's a legal document we rarely name paragraphs. But we give sections and chapters names. This often has the same challenges of naming in code. They need to be short and descriptive. Not always easy, but standard stuff for coders.

Single Responsibility Principle: When we write a class, as far as possible, we want it to do one thing only and do everything related to that one thing. Anything that deviates from that responsibility we try to move into a different class. Equally, we move aspects of that responsibility found in other classes into this class. We should aim for the same goal with the sections in our document.

TODOs: As with writing code, if you're not quite sure what to write at a certain point (maybe you need a reference, need to look something up or your brain is just melting), add a TODO comment. For example: "### TODO: Add link to IETF HTTP spec". If you are adding them into a word processor document, consider putting them in a different style so they stand out better. You can then also hide them if you want to make a pre-release!

Idioms and Patterns: As you write more code you find yourself repeating idioms and patterns over and over again. The same applies to writing documents. I like the "For example" pattern. You write a piece of text describing something and then say ", for example:" and show some example code or similar. The "for example:" ends up being the equivalent of the green tick on Stack Overflow! Over time you'll develop your own idioms and patterns that will make writing documentation easier and faster.

Unit Testing and refactoring / debugging: All code should be tested. For documents that means reading them. I personally like to print them out and set to them with a red pen, highlighting things that need changing. (For the younger generation who seem to eschew a printer, you are missing out!) If it's a small change, in addition to the correction in the text, I make an additional bigger mark in the margin so there is less chance of missing it when I come back to editing the change back into the document. When I merge the edits back in, I strike through the markings using a different coloured pen. However you do it, make sure you test and refactor. Fix typos, reword, add or remove text, move blocks of text around, add in new paragraphs, etc, etc. All operations that are analogous to standard software refactoring. Once you've refactored, re-test by re-reading. (I usually have to do this a minimum of 3 or 4 times. I recently wrote a small book and it took me 15 iterations!) (With unit testing in code we have an explicitly written test. In the case of a document the test is implicitly in the author's head: "Does this text describe what it's supposed to in a concise and unambiguous way?")

System testing: Go through your document and check that all your requirements have been dealt with.

Prototyping: Don't wait until you've decided your document is perfect before letting your colleagues see it. Timely but incomplete is better than perfect but too late. They can also give you valuable early feedback.

Deployment testing: Software may work great on your system but may be missing libraries and components when deployed on a remote system. Similarly, some things in your document may be obvious to you but not to others because you have additional knowledge. Ask some colleagues to read it and give feedback on anything you might of missed or needs further clarification.

Modules: Some software projects are too big to be treated as a single project. The solution is to break the task down into modules and libraries and develop them separately. The same can be done for bigger writing tasks such as end of year reports and theses.

README: Every good GitHub project should have a README. The README allows the reader to decide if this software does what they are looking for. The equivalent for documents is the abstract. There is also other boilerplate type material in a repo such as the LICENSE file and contributors. For a document these map to things like introduction, conclusions, references and tables of contents. Just bash them out. (It's best to maintain the references section as you go along. I use the "[<short word>]" form - e.g. "[Python]" - instead of the "[<number>]" form as it is easier to maintain. I then sort them alphabetically in the references section. Your local style guide may have different ideas though.)

Bug reports and maintenance: Like software, documents are rarely perfect. In fact, in a software development environment, documentation is an area where you can get away with cutting a few corners. If there's a few mixed up "your" and "you're"s it's no biggy. But if in the haste to get something out, a colleague finds something confusing, be prepared to re-write that section and ask them if it's an improvement.

Version control: It's good practice to use version control when writing software. I do the same when writing documents. I do this manually rather than using something like Git. Just have multiple copies of the file. I'd name the copy I'm working on something like "Document.docx". Before starting another iteration I'd take a copy and name it "Document v1.docx" then work on "Document.docx". (I also wrote a little desktop utility program that I can drag a file over and it will make a copy and append the date to the file name.)

And that's it! Writing documents and reports uses exactly the same skills as writing software. It's just programming in English! And you know you're brilliant at programming.

References

[Pomodoro] https://en.wikipedia.org/wiki/Pomodoro_Technique

Comments

Have comments on this article? Add them to the thread on Twitter.