You might have the greatest software invention since the QuickSort, but if you do not document it appropriately, then  people will not adopt it. This applies whether you are a lone developer writing an article about a neat library you’ve created, or whether you work for a large corporation who sells sophisticated software tools for enterprise software development.

For purposes of discussion, let’s consider the lone developer. All too often I read articles about some clever software package that explains what it does… but not how to use it. Typically, the reader must download the project and load it into Visual Studio (or Eclipse, etc.), then spend significant effort deconstructing what the author has done. Let’s say that takes anywhere from 30 minutes to a few hours, depending on the reader and the project complexity. Let us further assume for simplicity the article had only 1000 readers. That means 500 to 3000 person-hours will be invested across those 1000 people, to figure out the value of the product! And that time is not spent producing any work! After digesting the project, the reader must then put in the time to actually use the product.

If instead, the author had put in another few hours (or even another few dozen hours) explaining how to use the product, that effort would not have to be duplicated over and over again by each reader. Moreover, the author has expert knowledge of the product; any reader comes in as a product-novice and is bound to miss some of the subtleties. That will, in turn, lead to more debugging time down the road; assuming up to five hours of debugging per reader, that potentially adds up to another 5000 person-hours invested in this product. What a trade-off—and what leverage the author can wield! A few hours by one person can save thousands upon thousands of hours in the larger software development community.

Why neglect the documentation? Firstly, those who create software are notoriously averse to doing documentation. Secondly, if you go to school for computer science, computer engineering, or the like, you will learn all about programming but very little about documenting. So something that you already do not want to do is in fact harder if you’ve not learned how to do it, thus exacerbating the problem. Finally, even current trends seem to promote eschewing documentation: the Agile Manifesto loudly proclaims “Working software over comprehensive documentation”. But if you read the fine print, the Agile Manifesto does not state that you should avoid documentation. It essentially states that documentation does, in fact, have value… once your software actually works. And I submit, it has significant value: it is the One Big Hurdle between people using your software and—the unthinkable!—not using your software.

Ralph Waldo Emerson famously wrote, “If a man has good corn or wood, or boards, or pigs, to sell, or can make better chairs or knives, crucibles or church organs, than anybody else, you will find a broad hard-beaten road to his house, though it be in the woods.” [Wikipedia] You might know that better in its modern form, “Build a better mousetrap and the world will beat a path to your door.”

Alas! Just having good corn, or well-built crucibles, or cleverly-constructed mousetraps is not sufficient to guarantee success or prosperity! In fact, the “build a better mousetrap” fallacy has long been known as a well-known marketing myth. As stated in Seven Marketing Myths that Devastate Business, George Torok wrote “The reality is that you need to market. The difference between the financial failure of Van Gogh and the success of Picasso was marketing.” But there’s more to it than that. The Mousetrap Fallacy analyzes the problem in more detail, suggesting that people have to:

1. know about your product,
2. need a product like yours,
3. be convinced that your product is better, and
4. believe that your product offers the best value.

Only then will you find “a broad hard-beaten road to your house”.

Point 1 is essentially marketing, as already mentioned, and I will say little more about that. Point 2 is arguably out of your hands, but not entirely; educating the consumer can bring realization of a perhaps unknown need. And points 3 and 4 are largely in your hands. To put this all in the scope of software development, a product can only be evaluated as better than its competitors and having the best value amongst its competitors if developers understand the level of effort required to incorporate your product into their architecture (in the case of, for example, a library) or workflow (in the case of tooling).

Example of Doing it Right

One of the extensions that adds tremendous productivity for me as a typical .NET developer is OzCode. OzCode adds a number of bells and whistles to the user experience of Visual Studio. Though calling them “bells and whistles” is a mischaracterization; that implies they aren’t essential, and these are. I submit that OzCode extensions to Visual Studio are as vital as JetBrains’ ReSharper or DevExpress’ CodeRush. Once you have used ReSharper (or CodeRush), you likely would find it inconceivable to ever use Visual Studio without it! The same holds true for OzCode. Consider the “Reveal” feature as just one example of something I could not live without. I’ll quote the website in concisely explaining it, with just a couple edits for clarity:

Objects can have many properties, but when debugging, not all of them are useful to you. You’re usually interested only in a selected few. For a Customer class, it might be the ID and Username properties, for a Point in 3D space, it might be the X, Y, and Z fields. With our “Reveal” feature, you can finally focus on the data that actually matters. Star the properties you are interested in and they will appear right next to the object. If you have, for example, a collection of Customer objects and you are mostly concerned with the full name and customer id of each, simply open any item in the collection, tag those properties, then close that item back up. Immediately all the objects in the collection show values for just those properties. Your choices will be persisted across debugging session and across different Visual Studio solution files.

Well, that description might have caught your fancy, but accompanying that text is a 10-second inline video that actually shows it to you. As this is a static medium, here are a few key frames from that video:

1. Open the collection in the debugger. (Having not revealed anything yet, about the only thing you can easily glean is the number of items and the type of each item.)
   
2. Open an item, any item. Find the FullName property and move towards its accompanying “favorite” icon, the star.
   
3. As soon as you click the star, that property bubbles to the top, as a starred/favorite item.
   
4. Repeat that for the Id property as well. Finally, close up the expanded item, so you are now back to just viewing the collection, and you will see that all items in the collection now reveal (hence the name of this OzCode feature ) just those properties that you have tagged.

My first reaction to seeing the above was: what an amazing enhancement to Visual Studio debugging!

But my second reaction was even stronger: what amazingly effective documentation! Not only did that short text and short video explain what the particular feature does and how to use it, but it revealed (pun intended) to me that I had been laboring with a problem I did not realize I had! I had been plodding along in my occasional debugging by opening the collection, then opening the first object in the collection to check the name, then the second object, then the third object, etc. This feature documentation, along with the many other features available in OzCode, demonstrated that OzCode would easily pay for itself quickly in terms of increased developer productivity.

Son of Joel

‘Documentation is the castor oil of programming . . . the managers know it must be good because programmers hate it so much.’
Gerald M. Weinberg; The Psychology of Computer Programming 1971: p 262

You have likely seen Joel Spolsky’s eponymous Joel Test, a way to rate your company (or a prospective company you want to work for) in terms of progressive/aggressive/innovative attitude. And then there was John Sonmez’s follow-on Joel Test to rate programmers (evaluate yourself or evaluate candidates you are considering hiring). In a similar vein, I present below the Documentation Test, a way to rate how well your software’s documentation pitches itself in terms of value and productivity.

Don’t turn away, readers, don’t turn away! Force your eyes back up the page and read it again. I know, I know, you want to code. Well, if you have a marketing department you are in luck. But if you are working on an open-source project, or even if you are just writing an article about a piece of code you want to share, you are it. (And besides, even with a marketing department, they can prettify your message, but the content of the message is up to you, the developer.)

Now you might, at first glance, think this list is burdensome. But I challenge you: take off your developer hat and put on your user hat. That is, assume that you now need to find a software tool or library to do a specific task. You need to go shopping and evaluate choices you find. Don’t you think that it will take you less time to evaluate, and you will have a better grasp of the scope of a product, and you could integrate that product into your workflow more efficiently, if it has a high rating from the Documentation Test?

Let’s consider the items on the test individually.

I. Documentation is available without installing the product

When you first start out looking for a product, you want to scan quickly. You look over the home page to get a feel for the company (if commercial) or the size of the endeavor (if open-source). But you also want to see some examples, some use cases, some how-to’s, etc. quickly. You do not want to have to download and install the product just to peruse the documentation. A prominent violator of this guideline is TFS Power Tools , a useful and popular Visual Studio extension that provides a large assortment of new capabilities that manifest in many different ways: some are on context menus within Team Explorer or Source Control Explorer; some are subcommands of a new executable tfpt, some are PowerShell cmdlets, etc. The problem is the single, short page of documentation in the Visual Studio Gallery is very vague, not even listing what most of the features are! And once you install the product, it does not provide a large neon arrow pointing you to the documentation. Rather, first you have to realize that it is not just shell extensions and context menus, so it has an installation directory under C:\Program Files (x86)\Microsoft Team Foundation Server 2015 Power Tools. Then, under there, the actual documentation is …Help\Index.htm. And that references a series of .mht files that—for those of you not familiar—is a Microsoft-proprietary HTML format that only be opened by certain browsers (Internet Explorer and Chrome, but not Firefox, for example).

II. Dependencies are specified (e.g. .NET 4.5, Java 9, etc.)

It is important to a lot of us to know up front what other baggage might be needed to use a particular package. Do I need node? Do I need Python? Do I need Java? (There was a period some time ago when I tried to be Java-free due to a rash of security concerns so I refused to install anything that required a Java runtime engine.) Beyond personal preferences, it is quite possible that your company has policies regarding what are officially sanctioned—or prohibited—frameworks.

III. Prerequisites are listed (8MB, Windows 8.1, etc)

If you are still running Windows 8 but a package is designed to only run on Windows 10 or above, then there is no point reading anything further on it. The inverse is a common scenario, too: a package is designed to only run, say, on Windows XP, but you are running Windows 10, so you are mostly out of luck there as well. (For simplicity, I will ignore the notion of loading it on a virtual machine with a compatible OS.) As another example, gaming software is well-known to be resource-intensive so you might need a certain level of graphics processor. Thus, generally, there are a variety of things about actually system prerequisites that should be easily available to you at a glance to prevent you from going down a rabbit hole investigating a product that is not viable for your situation.

IV. Describes what the product does

This is the one that is rarely missed entirely. Most products, projects, or libraries say something about what they are delivering. However, I submit that it is quite often the case that the given description lacks sufficient detail. Certainly, it should include a high-level summary—call this the marketing pitch if you will—that is what folks will use to make a quick, initial assessment of whether they want to proceed to learn more about your product or not. But “what it does” also must include the details of all the user-facing features of your product.

V. Describes how the product is different from similar products

Part and parcel of the above is what makes your product stand out. What is different out about it compared to its competitors? If it achieves the same functionality at a significantly lower price point, that is clearly worth mentioning. If yours costs more, explain why the added value yours provides more than makes up for the initial up-front cost. If you have different versions of your product (enterprise, professional, home, community, etc.) this should also include a concise chart showing which features are included in which editions. For instance, Microsoft provides both an overview (shown here) and a detailed table of what features are in each edition of Visual Studio 2015:

VI. Describes how to use the product

While test item #1 is probably my favorite pet peeve, item #VI is arguably the most important. It is all well and good to describe what features your whiz-bang product offers (per item #IV), but it is vitally important to explain how you actually use each of those features. It is a question of economics, as I explained earlier. A bit of time and effort on your part saves an enormous amount of time and effort on a grander scale; the more people that might be interested in your product, the larger the multiplier of this effect. One of my all-time favorite libraries for .NET development is moq, a hugely popular mocking framework for .NET. The home page link given provides a nice overview of the what (item #IV) and the Quick Start page ostensibly explains the how. But… not so much. (In fact, as far back as 2008, people have been questing for moq’s documentation.) The Quick Start is not so much a quick start as it is a quick reference; i.e. it is very useful—once you know how to use moq. When I first encountered it a couple years back I was able to get up to speed quickly but, to be frank, that was due in large part to my colleague at work who, having already mastered moq, was able to guide me through a good understanding of it.

VII. Documentation is up-to-date

Last but not least, once you’ve labored long and hard to satisfy all the other items on this test during initial development… then you get to the maintenance phase. Has your API changed? Have you removed some unwieldy feature? Has your product evolved to have, for example, instead of a single set of features, a separation between beginner and expert features? Whatever changes may have occurred since you initially wrote your documentation, you need to make sure your documentation changes keep up with your code changes.

Conclusion

I was tempted to name this article “How to Contribute Thousands of Actual Man-Hours to a Software Project in the Merest Fraction of that Time” but I was certain my editor would balk at the length of that… not to mention the huckster-like sound of it. But now that you have reached the end if I have done my job right, you can see the truth, as well as the value, in that statement. I could imagine that some of you would have the reaction “Easy for [me] to say!” because, well, clearly, I like to write. So the next time that you, as a user, grab that open-source library, or that “free” extension for your IDE, just note down the time you spend in getting it to work, figuring out what it does, and how to use it. You will quickly discover that “free” has hidden costs. And, of course, that applies almost as severely to commercial products, i.e. the cost is higher than it appears for the same reasons. So my hope is that you will pay it forward, and invest a bit more effort in your own development efforts to go out there and document, document, document!