From observation of the computer industry going back to 1987, when I did a pre-university year at IBM Scientific Centre in Winchester, it seems that the very brightest and best programmers (software creatives) are often not very good at or not very keen on documenting their work.
I think the reason for this is often misunderstood. Poor documentation is a source of great consternation in the world of Linux. In fact it’s a large part of the raison d’être for RasPi.TV. We, the users, often feel that the geniuses who write awesome software can’t be bothered to write good instructions for it because…
- it’s beneath them
- they’re lazy
- they think “it’s obvious how it works unless you’re a retard”
…and, in some cases, there may be some truth in some of those statements. But I suppose the real reason is different. They find creating and writing great software quite a stimulating and fun mental challenge. But, for them, writing instructions is totally boring. And since, when we have a choice, we all naturally shy away from doing things that we don’t enjoy, a lot of Free and Open Source Software (FOSS) remains…
- badly documented, or
- incompletely documented (or permanently out of date docs)
I think it’s the nature of the beast. Free software is free because someone enjoys writing it. But once you’ve sweated long hours over debugging your code and it finally works just as it should, you feel like it’s finished. At that point, the thought of going through it all to show people how to use it may well seem quite repellent. “I’ll have a rest and do it next week.” You think to yourself. But next week a new and interesting programming challenge comes along and the documentation gets swept under the carpet and forgotten about.
Professional Manual Writers Do Exist
Back in 1987, at IBM, I met a guy who was a professional software manual writer (Technical Author). That was a new one on me. “Wow. You mean people actually write these things for a living?” This guy’s job (I’ve forgotten his name) was to play with the software alongside the guys who were writing it and make them show him how it worked. Then he’d convert that knowledge and information into a readable user manual (oxymoron?). The software in question was called IAX – an image processing system, which ran on a mainframe. The digital cameras back then were huge and cost tens of thousands of pounds.
So this guy’s full-time, well paid job was to write software manuals. I don’t know if this approach is still taken in the world of paid-for software? Judging by the quality and comprehensibility of some software guides and built-in help, you’d have to guess “not always”.
But it certainly doesn’t apply in the world of FOSS. Some people are great at documenting their work. Others aren’t. This leaves a niche for people like me, who are willing and even sometimes enjoy embracing the challenge of figuring out how something works and writing “bullet-proof instructions that work first time” for those who want or need them.
So How Should We Document Our software?
The answer depends on how complex it is. For something really simple, a ReadMe file or comments in the code might be enough. For something more complex, a web page or even a fully-fledged user guide may be in order.
Peter Onion pointed out shortly after I published this article that, carefully chosen variable names can greatly reduce the need for comments.
— Peter Onion (@PeterOnion) January 5, 2015
Particularly in languages like Python, your code can often read almost like English, so the need for comments can be eliminated or greatly reduced.
Comments in the code
Here’s an example of commenting in the code…
# This is a comment in a Python script. # Anything preceded by a # is ignored by the program # The official way to comment is to write your comments # as separate lines immediately before the # section of code they describe. # Official way to comment... # Here is a simple loop from 0 to 9 for x in range(10): print x # Alternative way. Not officially recommended, but I sometimes use it... for x in range(10): # this is an inline comment - I like them if kept short print x # as you can see uninterrupted flow of the code
Schools Sometimes Get It Wrong
Apparently, in some UK schools, a lot of people are taught to write long comments inline on every line. This is highly questionable! It’s considered best practice to keep your lines ~85 characters’ length or less. Inline comments that increase line length >>85 are not a good idea. And the idea of commenting every line is ludicrous!
There’s a common saying that you should comment your code as if the person who will have to maintain it is an axe-wielding psychopath (i.e. Plenty of comments, clear enough to explain what the program is doing).
A “Readme” file is simply a text file, usually called ReadMe.txt, which accompanies the files for the software you’re creating/installing/using. It’s used for cases where a full-blown manual is not needed, but where simple program commenting is not enough. If you do a ReadMe file, you should still put comments in your code, as it will be easier to understand the code if you come back to it later.
An example of a ReadMe.txt file can be found in the GertBoard Python Scripts I wrote a couple of years ago. There’s a ReadMe.txt file in the .Zip file
This one contains information like a full list of programs, installation instructions and usage instructions.
If your software is really involved or complex, a manual might be in order. This is really just a comprehensive set of instructions for how best to use the software. I include it for completeness, but the chances are if you’re reading this article you’re not yet writing software that requires a full-blown manual.
Lots Of Examples Please
However you choose to document your work, it’s great if you can have plenty of examples including code snippets. It’s quite hard scanning through a list of options, parameters, operators, arguments, modifiers and tags to work out the exact command syntax required. Please try to show examples of each (if used) in your documentation. The world will thank you for it.
Examples are worth a lot more than descriptive text.
Document As You Go
If you are documenting your own work, why not do it as you go rather than leaving it all for the end (where it won’t get done as it’s too big a task)?
I read an article the other day that advocated open sourcing your code from day 1. This forces you to be thorough right from the start. It might be a bit of a radical step for some, but it does make you think. I can imagine if you open source from day 1, you’ll be commenting and documenting your code well from day 1 too.
Testing, Testing, 1, 2, 3
Most importantly of all? Test everything. People will take for granted that your examples should work if they cut and paste them. Make sure you test the exact code snippets from your documentation to avoid confusing the hell out of all your users. Also try to make sure that your publishing platform doesn’t mangle or alter the commands. (I’ve noticed that WordPress mangles Python indents horribly unless you use a plug-in.)
It takes a bit more effort at the time, but you will have fewer people emailing you with support queries, so it’s well worth it.
I usually base my tutorials upon a complete run-through of a procedure. For something complex, it’s really the only way to be sure. And even then, things can change with time and go out of date.
If you get queries or feedback about a problem, remember it may be necessary to revisit your documentation to change something that no longer works. This may also happen if you change your software. Do your best to try and keep the documentation up to date as well. Then you will look good and you’ll have happy users. Many people who publish open source software get asked to write software or do other work (freelance and paid) by people who’ve seen what they can do. It’s like a viral form of CV. I can think of at least 5 people in the Pi Community (including me) who have leveraged their open source work in this way.
When you look at it that way, it kind of makes you want what you put out there to be a reflection of your very best doesn’t it?