The Importance of Software Documentation (“Document … why bother? Just ask Jim, he knows”)

It seems that there are some businesses that rely heavily on tacit knowledge (“Tacit knowledge,” 2013) to run their IT services. Documentation is seen as non-value added activity (“non value added activity,” 2013). When there is a problem with an application, there is usually a name associated with the application; a go-to person. This approach places a company at-risk. One of the phrases we used to use at one of my places of employment was: “What if Jim gets hit by a bus, or wins a million dollars?”. Exactly. What happens if the person with all the unspoken, undocumented, knowledge about an application (or process) is away from the office, even if it’s for a sick day? Does the business just simply wait for the return of the Oracle? Is the response to customers, “Oh, you’ll have to wait on that financial application to be fixed, Jim is away on vacation”?

This may seem like a very caustic way of looking at software documentation, or lack thereof. Joel Spolsky in a blog entry stated: “Why won’t people write specs? People claim that it’s because they’re saving time by skipping the spec-writing phase. They act as if spec-writing was a luxury reserved for NASA space shuttle engineers, or people who work for giant, established insurance companies. Balderdash. First of all, failing to write a spec is the single biggest unnecessary risk you take in a software project. It’s as stupid as setting off to cross the Mojave desert with just the clothes on your back, hoping to ‘wing it.’ Programmers and software engineers who dive into code without writing a spec tend to think they’re cool gunslingers, shooting from the hip. They’re not. They are terribly unproductive. They write bad code and produce shoddy software, and they threaten their projects by taking giant risks which are completely uncalled for” (Spolsky, 2000a).

One widely held opinion on software documentation is the use of self-documenting (“Self-documenting,” 2013) code to fill the gap between business knowledge and what the software actually does. In a blog entry by Ian Lotinsky, he states: “Make it obvious why a non-obvious approach was taken. Save your fellow engineers and your future self from re-exploring the explored, re-arguing the argued, and re-deciding the decided.” (Lotinsky, 2013). Although I agree with the idea of self-documenting code and reducing the amount of code commentary, I think the why is just as important, not easily captured in code, and requires secondary documentation to fully define the context in which the code was written. One other consideration is the end user of the documentation. Most companies will not allow end users access to code. Writing self-documenting code, although extremely helpful, doesn’t help the end user to understand the usage of the software, or how it supports a business process. More importantly, it wastes time. Sometimes the end user has a question about what to expect the application to do, especially if the application has been in use for several years. Human memory being what it is, people forget what the software was originally intended to accomplish. Now, instead of consulting requirements documentation, a developer has to dig through self-documented code to discover the original intent of some part of the application’s functionality.

Let’s return to my rather heavy-handed set of statements at the start this blog entry. There are companies seemingly attached to the idea of one person knowing everything there is to know about one software application. That’s fine. There should be an expert available with full knowledge on the subject. On the business side of Information Systems (IS), the go-to business people are referred to as SMEs (subject matter experts), and every company should have at least one on the payroll. An SME adds context to the business process that may not be easily captured. Experience is the best teacher, and even outside of IS there are wise sages in every aspect of industry. However, a sage is no substitute for documenting why a business process exists and how it operates.

Documentation should give context to what the software’s purpose is in the organization. Documentation, as described in a blog post by Scott Hackett on writing effective design documentation, “is a way for you to communicate to others what your design decisions are and why your decisions are good decisions” (Hackett, 2007). The same approach applies to all software documentation. It’s just like the writing skills taught in primary school. Documentation gives the who, what, where, why, and how, of the software and the business process it supports. Documentation communicates specifics about the application. If I click the “Submit” button, what happens? If I enter an invalid date, will the application tell me the date I entered is invalid?

Joel Spolsky gives some suggestions on what functional specification should look like (Spolsky, 2000b). “A functional specification describes how a product will work entirely from the user’s perspective” (Spolsky, 2000b). Without a functional specification, designing an application becomes a tedious and costly task of back-and-forth between developers and customers. The dirty little secret about writing code is it’s simple and anyone can learn how to write code (yep, I said simple and anyone can do it). What is difficult is writing code to behave in a specific way. There are plenty of examples on how to write object-oriented Java code, use Spring and Hibernate, but all the examples in the world cannot show someone how to write a financial application to meet the company’s needs – because each company has different needs. Even commercial-off-the-shelf (COTS) applications are geared towards very basic business problems, because providers of COTS solutions know the software will be configured and customized to meet specific business needs. Documentation outlines how an application is expected to behave, and does so in a very non-emotional, non-political, business-oriented, way.

Some complain that maintaining documentation after its initial creation is a costly and time-consuming effort, with little benefit to the business. There is a simple way to confront this complaint – add documentation creation and management as part of the software development process. Reviewing the business process before and after a proposed change will expose issues before they become problems. This statement becomes especially true when the application being changed impacts another applications’ behavior. Imagine the payroll application is updated, but the budgeting application is forgotten about and is later impacted by the change. This issue could be addressed early in a project before it enters the development phase. Additionally, properly maintained documentation offers a starting point for innovation and process improvement. How can a process be improved through software automation if the process is not fully understood?

Software documentation, even though it appears to be a non-value added activity, is an important step in the software development process. Without software documentation, software is updated in any haphazard fashion one person sees fit to implement.

References:

  1. collaboration – What to do with star developers who don’t document their work? (2010, February 7). stackoverflow. Retrieved July 28, 2013, from http://stackoverflow.com/questions/532338/what-to-do-with-star-developers-who-dont-document-their-work
  2. Hackett, S. (2007, May 2). How to Write an Effective Design Document. “Hello World” – The SlickEdit Developer Blog. Retrieved from http://blog.slickedit.com/2007/05/how-to-write-an-effective-design-document/
  3. Lotinsky, I. (2013, March 6). Document the Why. on software engineering, all things web, and, sometimes, real life. Retrieved from http://ianlotinsky.wordpress.com/2013/03/06/document-the-why/
  4. non value added activity. (2013). BusinessDictionary.com. Retrieved July 28, 2013, from http://www.businessdictionary.com/definition/non-value-added-activity.html
  5. Self-documenting. (2013, July 22). In Wikipedia. Retrieved from http://en.wikipedia.org/wiki/Self-documenting
    Spolsky, J. (2000a, October 2). Painless Functional Specifications – Part 1: Why Bother? – Joel on Software. Joel on Software. Retrieved from http://www.joelonsoftware.com/articles/fog0000000036.html
  6. Spolsky, J. (2000b, October 3). Painless Functional Specifications – Part 2: What’s a Spec? Joel on Software. Retrieved from http://www.joelonsoftware.com/articles/fog0000000035.html
  7. Tacit knowledge. (2013). TheFreeDictionary.com. Retrieved July 28, 2013, from http://www.thefreedictionary.com/Tacit+knowledge