Which came first, the program or the documentation? Therein lies the dilemma.
I don't think I have ever heard anyone say, "This documentation is great." Mostly I hear how badly some specific documentation sucks, and I have repeated that refrain myself many times.
And yet there is a lot of really good documentation out there. For example, the documentation for LibreOffice is excellent. It includes several documents in multiple formats including HTML and PDF that range from "Getting Started" to a very complete user's guide for each of the LibreOffice applications.
The documentation for RHEL and CentOS, and that of Fedora—which are all very closely related distributions—are also among the best I have seen in my more than 40 years of working in the IT industry.
Good documentation is not easy and takes time. It also requires an understanding of the audience—not only in relation to the purpose of the documentation, but also the technical expertise of the intended readers and the languages and cultures of the readers. Rich Bowen covered that quite nicely in his great article, RTFM? How to write a manual worth reading.
The problem that I encounter is that many managers do not see documentation as a high priority. Documentation can take a back seat to those concerns, and I am not talking only about development managers and new code.
I have been involved in many aspects of the IT industry. Fortunately most of the companies I worked for believed that documentation was not only important, but that it was crucial to the task at hand regardless of what that task was.
My philosophy is one that has been drilled into me by my best mentors over the years: "The job is not done until the documentation is complete." This means that everything must be documented.
Customer documentation
As one example, I currently own a small LLC through which I do a bit of consulting. When working with customers, I always document my interactions with them and the work I perform. In some cases, I have years of documentation that covers everything from my first contact with them to the information I discover about their network while I am working on projects for them, the details of hardware I install for them, details of my work on projects, and a record of each time I install updates. I include data in these records such as network diagrams and tables of network IP and MAC addresses with notes about the function of each node. I also keep the output from a script I have written that lists the hardware and some of the configuration details of each Linux host that I work on.
This information has multiple uses. It gives me a record so that I can go back and recall what I have done and the structure of my customer's environment—it is a memory aid for me. I can use it to support my recommendations for additional work when needed. Keeping detailed records also can be useful in the event of a dispute with a customer.
I always create a task list before performing work for a customer so that I do not forget anything that needs to be done. I take notes on that list and then, at the end of the work, the task list becomes part of the documentation of the work I have performed and is supplemented by the notes I took during my performance of the work.
Documenting code
Documentation of code requires different information and a different approach.
The first thing I do is document the source code, which is almost always Perl or BASH scripts for me. In fact, in one job I took a number of years ago, I was to maintain a large number of preexisting Perl CGI programs that were used as an interface to a complex email administrative front end. The code was OK, but a bit convoluted and lacked any comments or documentation of any kind.
My first task was to fix a few bugs in different CGI scripts. I first started reading these scripts to determine what they actually were supposed to do. As I determined what each section of code did, I added comments that would document the code I had just read and interpreted. Just in the process of doing that, I was able to determine the cause of the bugs and correct them.
After I completed my task of commenting each CGI script, I could then simply copy the comments out into a separate HTML document that became—with the addition of some headings and explanatory text—the body of documentation I was also supposed to create.
When I am writing new code or maintaining existing code, comments are the first thing I add. Starting with comments allows me to outline the structure of the code I am going to write. Then I can write the code that enables the actions described in the comments.
But I don't even do all of the comments to begin with. I first create a basic outline containing a bare framework of comments describing the logic of the program. I then create the code to implement that basic framework. Then I work on the individual branches to first comment them and then to write the code.
This is the answer to the question I posed at the beginning. For me, at least, the documentation comes first. I can hear the Agile proponents' keyboards typing their comments already. But in a very real sense, what I am doing is Agile, because I write just the documentation I need, just in time to write the code. And then the comments become the external documentation as well.
Not everyone will want to work this way or will find it as well suited to their modus operandi as I do. There are as many ways of creating code and documenting it as there are people doing it. Just do what works best for you.
Issues
I have had a few issues with my own documentation. First among them is neglecting to update documentation in a timely or complete manner. This has caused problems when information I needed had not been properly recorded. When I discover I have been lax in my documentation, I go back and correct it as soon as possible.
File compatibility can also be an issue. For several years I used some Linux software that maintained my data in a format that was not just plain text and was proprietary in the sense that it was not documented and in a format which no other software could access. This is at least in part because I was not aware of the data format and that is my own fault.
Tenet 5 of the Unix/Linux Philosophy is "store data in flat text files." This program violated that tenet. So when a program upgrade failed to properly upgrade the database in which the data was stored, I was unable to access customer notes from several years.
I am still violating letter of that tenet, if not the spirit, because I now store my notes in Open Document Format (ODF). However ODF is a well-known, open, and documented format and there are many applications that can work with it. Although the tenet specifically refers to program data, I believe that a corollary should be that documentation should be maintained in an open format such as ODF.
Whatever you do and however you choose to work, just remember that the job is not done until the documentation is complete.
1 Comment