This Practice starts off a new section, on documentation. I think there’s at least one point in this chapter I disagree with Mr. Conway’s conclusions, but we’ll get there presently. In general, I think he has valuable things to say, and the issues are worth thinking about and deciding on.
Documentation is important, and it’s something many of us are terrible at.
The first Practice he suggests is to be aware there are several kinds of documentation, and to separate the user documentation from the technical documentation.
This is actually just basic writing practice – know your audience. You don’t use highly technical language writing for six year olds, and you rarely discuss mice who write motorcycles when writing for PhD’s.
The Practice suggests keeping user documentation and technical documentation separate. It suggests the public parts of POD for user documentation, and private parts of POD or comments for the technical documentation. They’re different documents for different audiences. The book goes on to describe in more detail what they mean, and what might go in what type of documentation, with reasonable examples.
This is fine, as far as it goes. I think documentation is really important, and that not only are there multiple audiences, there are multiple types of documentation.
Most programs wind up with POD that contains reference documentation. It has a long list of functions or methods, each of which explains what the parameters are and the return values. They might even each have examples.
Nowhere in most POD do you get the explanation of why you need these things or what the module exists to do. The abstract information needed to understand the details is not present.
Have you seen an application with a dialog box with a field labelled “First Name”, and a text box, where the on-line help says, “Provide the user’s first name.” That’s reference documentation of the worst kind, because it was obvious. I probably guessed that a user’s first name went in the “First Name” text box. I bet I even guessed that their surname went in the “Last Name” text box. What I don’t know is why I’m providing a name, what will be done with it, and how it relates to the other parts of the system. Will this be a user name? A login ID? An e-mail address? Who knows! It’s a First Name, and a Last Name. I’m so relieved that the on-line help clarified that for me.
Now, maybe this kind of information doesn’t belong in the POD for a module. But if it isn’t there, where else will it be, especially where will it be that the programmer writing and maintaining the thing will see it to update it? It might be in a separate POD file. It might be on a Wiki. It might be published in a paper. It might be on a blog post. It might be written on the back of a cocktail napkin lost in their desk drawer.
Wherever it is, the reader needs to be able to find it, and the author needs to be reminded it exists to keep it updated. My favorite way to do this is to keep it all together in the POD, so it doesn’t get lost. If that’s objectionable, the POD should provide a link to it.
A good friend of mine says, “If the user can’t find it, it doesn’t exist.” Does your documentation exist?
POD is good for both user and technical documentation, in particular because it is free form and it is optional as to whether it is in the same files as the code or written in separate files organized differently from the code. See for example what Moose and some other projects do, there is lots of non-API documentation in there, including tutorials and such.