Copenhagen, Denmark
(+45) 262 000 94
claus@techwriter.dk
Writing and Programming - Next of Kin
Writing good documentation is easier for programmers than for any other craftsmen.
Both writers and programmers put much effort into explaining that the two are nothing alike, but they are.
Consider this list of similarities, starting from the very basics:
| Programming | Writing | |
| I | It's an intellectual process that everyone can learn but fewer do well | It's an intellectual process that everyone can learn but fewer do well |
| II | You need to know a language, its syntax and its grammar | You need to know a language, its syntax and its grammar |
| III | You sit down and code because you have a plan. You envision a piece of software. | You sit down and write because you want to tell people something. You have a point that you want to get across |
| IV | You need a requirements-document for your piece of software in order to know what you're aiming at. This isn't hard to write if you know what you're building, and for whom. | You need an outline of what you want to write in order to keep it coherent. This isn't hard to write if you know what you want to tell the reader, and who the reader will be. |
| V | Later you need a design-document to point out exactly how you're going to implement what you sketched out in your requirements - which tools are you going to use, and how. | Later you need to decide the more specific structure of your document and how to use the language in order to get your point across. Should it be formal, sticking to the facts or should you spice it up to make it more digestible. Much depends on who you're targeting your text at. |
| VI | Now you start coding. The more experience you have, the faster this is and the more stable is your code. | Now you start writing. The more experience you have, the faster you write and the smoother is your writing. |
| VII | During the process you may bring in someone to look your code over to ensure that your it's readable by an outsider and that your decisions make sense. | During the process a different set of eyes can come in handy. Does your writing make any sense to an outsider and how is the flow, the rhythm. |
| VIII | Once you're done coding and have made some basic testing of the functionality, it's time for a code review | Once your document is written and you've cleaned out misspellings and bad grammar, it's time to present it to someone for comments/editing |
| IX | After code review you implement the changes the review suggested | After an editing session you rewrite the document to accommodate the criticism |
| X | Previous two steps are repeated a few times | Previous two steps are repeated a few times |
| XI | Now you try to abstract your code as much as possible, making it a thing of beauty | Now you tweak the language, refine your phrases and make it sing |
| XII | In an ideal world you now present your software to some end-users. After these have tested your software you take their feedback and go back to step IX | In an ideal world you now present your document to some outside readers. You take their feedback and go back to step IX |
| XIII | In an ideal dream world where time is of no importance you would redo step XII a few times | In an ideal dream world where time is of no importance you would redo step XII a few times |
Depending of the level of your professionalism and the amount of time you're given to build your software or write your document, you close the deal somewhere between VI and XIII.
The bad news for the programmer is that his steps include some writing - whereas the writer doesn't have to code to do a document. The programmer's steps IV and V each produce a document that, in order to meet reasonable standards, should be subjected to the writers' steps I through IX. On top of that the programmer might need to write an end-users guide, which should also get dragged through the writers' steps I through IX.
The good news for the programmer is that if he takes the time to do really good documentation, his software is more likely to succeed.
You can subscribe to a low-volume newsletter that will notify you when I publish something new around here.
