A Simple Framework for Documentation

  • June 2nd, 2016

But a written program has another face, that which tells its story to the human user. For even the most private of programs, some such communication is necessary; memory will fail the author-user, and he will require refreshing on the details of his handiwork.

Frederick Brooks, The Mythical Man-Month

Introduction

The other day I finished Frederick Brooks’ The Mythical Man-Month: Essays on Software Engineering. I picked it up used from Poor Richard’s, a bookstore in downtown Colorado Springs for a whopping $5. It is a seminal book on software development – both from engineering as well as project management perspectives.

The book was published back in 1975. And it might come as a surprise: it holds up fantastically. There are a couple reasons why it stands the test of time.

The first is that Brooks is a supreme writer. He combines clarity, expression, and humanity to a subject that often gets treated with anything but these qualities.

The other reason? It is still very relevant.

The wild thing is, with all the advances in computing in the last 40 years – Moore’s Law, and all – we’re still facing essentially the same problems. Perhaps they are even magnified more by the complexity we can now achieve. And why? Because human beings do not rapidly advance like the technology has.

Documentation

There are so many great sections of this book, but the one I want to focus on is the last of the book, “The Other Face”. This chapter focuses on documentation.

In my career as a professional software developer, I have used several systems for documenting code – PHPDoc, JSDoc, ESDoc. They share a similar format and syntax. These days I try to ensure that I have close to 100% coverage in my code.

But what about documentation outside the code? While 41 (!) years have passed since the release of The Mythical Man-Month, there still isn’t any agreed upon standard on how to document a code project outside of the actual code.

I mean, how many lousy README markdown files are there on GitHub – even though they suggest you start your project with one? While the Open Source revolution is amazing, it is probably not contributing to upping the average quality of software project documentation, to say the least.

A Prose Description

Every user needs a prose description of the program. Most documentation fails in giving too little overview. The trees are described, the bark, and leaves are commented, but there is no map of the forest.

Frederick Brooks, The Other Face, The Mythical Man-Month

Brooks gives us a simple numbered list of items to help us build our “map of the forest”:

1. Purpose. What is the main function, the reason for the program?

2. Environment. On what machines, hardware configurations, and operating system configurations will it run?

3. Domain and range. What domain of input is valid? What range of output can legitimately appear?

4. Functions realized and algorithms used. Precisely what does it do?

5. Input-output formats, precise and complete.

6. Operating instructions, including normal and abnormal ending behavior, as seen at the console and on the outputs.

7. Options. What choices does the user have about functions? Exactly how are those choices specified?

8. Running time. How long does it take to do a problem of specified size on a specified configuration?

9. Accuracy and checking. How precise are the answers expected to be? What means of checking accuracy are incorporated?

And here is an important thing to remember: “Most of this document needs to be drafted before the program is written, for it embodies basic planning decisions.

It’s my goal to come up with a modern system that incorporates these ideas. Not sure what I will do just yet – but for now I will be using this outline to document my README files.

Tags: , , , , ,

Leave a Reply

Your email address will not be published. Required fields are marked *