To paraphrase the line “If you build it, he will come” from the 1989 movie Field of Dreams, “if you write [documentation], no one will read it”. So yes, this posting is a rant about software documentation. However it is not about the how, what, when documentation is created. I am starting with the assumption that the architecture and design documentation is created before (albeit just-in-time) implementation and even better, the implementation interfaces are well documented in the source code files. And for those skeptics out there who’d claim that this is an unrealistic assumption or wishful thinking – I have been on multiple projects where this has been achieved. In fact, my experiences on these projects is my motivation for this topic.
As a technical leader or documentation author – it is disappointing to be answering detailed questions about X, when it is obvious that the engineer asking the question did not read the existing documentation for X. Which brings up the question – why didn’t the engineer read the documentation? My speculation as to why:
- There is so much documentation they don’t know where to find the information they are looking for and reading everything is not a realistic option.
- Because the engineer is not accustomed to writing documentation before starting implementation, they have zero expectations that such documentation exists. Yes, I know I am implying motives to behavior which is wrong. Stated another way, the engineer simply does not go looking for the documentation.
- The engineer read the documentation but was not able to understand or internalize it.
Answer #1 above is an engineering problem waiting to be solved. Answers #2 and #3 above are people/culture issues that are IMO much harder to solve.
Too Much Information
A well-documented software project can have hundreds (thousands?) of pages of documentation – not including the requirements. In addition, there are literally hundreds of source code files that contain comments that someone, at some point of time thought it was worth the time to write. There is a real problem trying to find a particular shrub in the forest. Case in point. I was working with another engineer who needed help understanding a sub-system that I had implemented. One of his questions was something I remember detailing the specific behavior of in a header file comment. It had been a while since I worked on the sub-system and I was fuzzy on the details. I wanted to read my comment before I answered him. But I couldn’t remember which header file I wrote the comment in! After a minute of trying to guess which header file, I resorted to grep’ing the code base by keywords to find the comment. It took four different keywords before I found the comments that I wrote.
You also need to consider the logistics of where the documentation is stored and document control (i.e. do you have the latest version). Some examples.
- A typically scenario is that the architecture and design documents are stored on some shared storage within the Company’s network. This means that you need to remember (or bookmark) a collection of network locations. The next hurdle. Is the document I read last week still the latest version? When each author has their own (and not necessary consistent) ideas on how to doing versioning, this is not as simple as it sounds. Collaborate tools that support simultaneous, multiple users reviewing and editing of documents greatly helps. But even with the latest tools – it is still up to the individual authors to commit to using them in team friendly manner.
- I have setup several CI build processes that runs Doxygen on the code base to extract the code comments into a set of linked web pages. The Doxygen output is included as part of the archived build artifacts. While not hard, it is a manual process to find the latest build artifacts, download the artifacts, and extract the Doxygen output. This is surprising a significant barrier for engineers, i.e. they don’t do it.
Being able to search all of the relative documentation in real time is an engineering problem that will be solved. Who knows, maybe this time next year I will just have to ask Alexa or Siri “is a model point write operation thread safe?” and answer will automagically appear in my IDE. For now I have settled for using grep and having the latest drafts of detailed design documents always open.
People
You can have training, policies, and team discussions about what documentation is available and how to access it, but it is so much easier for an engineer to hunt down a subject matter expert (SME) and have real time discussion. While in many cases this is a better outcome than the engineer having read the documentation. On the other hand, it can become a problem when an engineer has been given specific instructions to pre-read the documentation (and fails to do so) before having the live discussion with the SME. In this scenario the engineer is shifting their responsibility for learning the material to the SME. An SME’s duties include mentoring other engineers, but the mentoree is ultimately responsible for their own success (or failure). This is where company culture and individuals’ soft-skills have a big impact on how well (or not) these scenarios plays out.
The quality of documentation in terms of readability and people’s ability to comprehend it are dependent on the author and the readers. If someone reads a document and doesn’t understand it – who’s fault is it? I can remember my first year in college and being frustrated because I could not make any sense of my Calculus 101 text book, and that was after a taking AP Calculus in high school. Skip forward a few years. I had just started going back to college after having dropped out in my freshman year. Once again I was taking Calculus 101 and I distinctly remember saying to myself “hey I can understand the text book, why was it so hard when I was a freshman?” What had changed? Not Calculus 101. It was me. I would like to think that I was just as intelligent as a freshman as I am now, albeit less experienced 😉. What’s the point of this anecdote? It is not reasonable to expect authors to dumb down their material. It is also not reasonable to expect every reader to instantly understand the material. However, this does not excuse authors from being excessively esoteric or staffing a project with individuals that are not qualified for the tasks at hand.
A couple of quotes from my Patterns in the Machine book:
All developers are not created equal
People are messy
How effectively team members utilize or understand the documentation that is available is not an engineering problem. Which is my way of saying I don’t have any new insights or solutions on how to improve in this area. My only suggestion is to accept that all engineers are individuals. As individuals, they all differ in their experiences, interests, abilities, and skills (both technical and personal). Don’t assume that your coworkers are just like you.