Software Documentation: The Beauty And The Beast

Yes, you read it right, software documentation. It seems to me this is something we as developers are pretty poor at, but I believe it is just as critical of a deliverable as the software we create. On a recent episode of HanselMinutes Scott Hanselman quotes Yehdah Katz as having said: "As a tech community, we must treat documentation, marketing, logistics, infrastructure, art, etc. work with as much respect as engineering". This seems to be spot on to me and I would say the (obvious) underlying message is that currently, we don't.

Why discuss this now you ask? I've been spearheading quite a few projects at the moment focused on a software system's architecture. In doing this I've aimed to create a number of libraries that will create a solid foundation and standard implementation to enable the building of the system's components going forward.

I firmly believe in the mindset of 'Why reinvent the wheel?' and am happy to utilize projects that are not mine, but this is where we come to the issue under discussion... One road block I continue to experience revolves around documentation.

To be clear, there are a few aspects to this. There is knowledge of the existence of the tool, discover-ability of the documentation for the tool as a whole, completeness of documentation and discover-ability within the documentation for the feature of interest. At any of these points there is room for error which inherently makes the tool less useful.

A case in point: there was a DotNetRocks episode titled Making MSDeploy Work in which the guest(Robb Schiefer) discusses a number of ways in which his organization uses MSDeploy that he finds most other developers don't know about. One of the first commenters on that show, notes that the MSDN documentation is decent, but then he points to his blog and GitHub repo demonstrating some of the aspects of MSDeploy that he feels are more 'subtle'. Just listening to the episode opened up my eyes to a bunch of things I had no idea MSDeploy could handle. I tried 'Bingle-ing' MSDN MSDeploy looking for a starting point in their documentation for this tool. I found a few posts from 2008, but wasn't readily able to locate more. It's possible if there was a specific feature that I wanted to look up, the documentation would be pretty decent, but again, I would have to know the feature existed in the first place before I could know to search for it.

Another example that I personally wrestled with recently was creating a Multi-project Visual Studio template. The templating features provided with vsix seem to be pretty powerful, but I had to spend a tremendous amount of time and frustration getting my example to work. I created a short series of blog posts along with a GitHub repo to document the process I went through and lessons learned in the hopes of easing the process for anyone else, as I feel as though the final product was a very valuable productivity gain for our team.

I try to continue to work on my education and exposure in the industry through looking at blog posts and listening to podcasts. I am able to discover some items that way, but what about all of those who aren't as interested, or aren't given the leeway from their leadership to spend so much time mining through a lot of information that isn't relevant to them(let's face it, we are never personally going to work with 99% of the code/libraries that are out there). Even having done so, to take the next step and to try to start discovering more on my own, in many cases, proved much more difficult than I had hoped.

Yes, I understand, documentation can be a very time-consuming endeavor and a lot of times a very unappreciated endeavor as the library/language continues to evolve and the documentation needs to follow suit. As a developer, I understand the emotional reality that it is incredibly exciting to create new features/functionality, but writing about it is not. There have been so many issues that I've had to spend days 'Bingle-ing' for or pouring through source code to figure out how to get something to work. We don't seem to place nearly enough emphasis on telling people about those features or how to (best) utilize them.

Rationally(and we are supposed to be rational as programmers, right?), it seems obvious to me that one could create the most amazing feature in their software and if no one knows about it, its usefulness is extremely limited. It is also amazing to me because obviously some developer realized the need for and was excited about a feature enough to implement it, but then didn't bother to let others know about it. What is so exciting then if that great feature never gets used? Are we solely in this field for the self-gratification that comes from solving a problem even if that solution is never put to use? (Is a problem truly solved if the solution is never applied?)

As documentation can come in different forms(wikis, textbooks, tutorials, test suites), I also think it's important to note that there is an attitude expressed often that, it's open-source, just look in the source code. While having the source code available can be a valuable resource, most of the time when I'm looking to utilize a library, I'm looking to see what it does for me, not how it does it. Finding the exposed classes and methods, how to utilize them best or in what situations isn't always easy to determine from the source code itself. Most of the documentation I'm looking for, especially when just getting started with a new library, are simple ways to get my feet wet with a library so that I can feel comfortable with it and start experimenting with it more.

While I realize that this might sound as though I'm ungrateful to the creators of these libraries/tools, the exact opposite is what I'm actually trying to express. I greatly appreciate your contributions! Thank you! I feel as though you are making things better for all of us, but I want your library/tool to be able to be utilized to its fullest. Let everyone realize the full greatness of what you have created. Make it accessible! Document it!