Beautifully Lean Documentation

Your development team spends a lot of time creating formal functional specifications, design documents, and general documentation. They create a nice class diagrams, sequence diagrams, or flowcharts to be included. Sounds like your team did everything it should, right?

Well, not exactly. Where is the software? Documentation is nice, but one thing that I learn is that creating developer documentation is seriously overrated. The documentation end up being practically worthless in the end, mainly because of simple, organic growth of your software.

In many organizations, any documentation that does exist are most likely out of date, because no one wants to update them. The documents end up in some hole on your company’s intranet and will stay there forever. Even if your documentation is current, there is *no* guarantee that anyone would read or understand any of it. Other developers, QA analyst, business analysts and management don’t really want to read a 50-page document on your favorite piece of code. They will often skim it, with often a small subset of knowledge how it really works. As time passes, the amount of trust in documentation diminishes because the audience knows that the software changes.

I am not saying that there should be *no* documentation, but your documentation should be like a good book. It should captivate your audience and more importantly, be relevant to the current situation. The most valuable documentation has correct context and has need. Creating documentation for the sake of documentation will doom your project.

So, beautifully lean documentation is key to success. What does this mean? Well, there are many strategies for agile or lean documentation. However, to have beautifully lean documentation, I take a more minimalistic approach:

  • The source code itself is probably the most valuable documentation any developer can have. Therefore, I make it a point to create meaningful comments and use documentation generation systems wherever possible.
  • I think that the user stories provide better context for the software than any other written documentation. In essence, user stories detail what the software is suppose to do. Couple user stories with acceptance tests, the system becomes validated.
  • If the software has external service interfaces, then those need services need explicit documentation. There is no real way around it. However, the documentation is used as reference at this point and it usually only documents the service interface.
  • I normally document just the design decisions that I made. This gives developers an understanding of what I considered and, more importantly, what did *not* work. This will save other developers some time on research.

So, when I am working on a new product architecture, creating beautifully lean documentation allows me to concentrate on the software.

6 Responses to “Beautifully Lean Documentation”

  1. 1 Lawrence July 8, 2008 at 7:45 pm

    Great post! I agree with your views, especially those on the reasons why traditional developer documentation is worthless and overrated. It amazes me that so many organizations continue to insist on this deliverable.

  2. 2 Andrew July 9, 2008 at 2:36 am

    You sir are a genius!

  3. 3 Alexander Botero-Lowry July 9, 2008 at 4:43 am

    Your point about code being the best documentation is really interesting. On one hand, it’s absolutely wrong and on one hand it’s the only option and so completely right.

    Documenting an API is hard. It’s hard because the internal details of how an entry point in the API works can not always be put to text in a terse and simple form. There is this constant flux between whether an description of what an entry point does is too large, and thus will be unread, or whether it’s too short and thus won’t actually explain what is going on internally. This is especially the case with API calls that do a lot of stuff internally.

    To be more concrete about that I have an example. Lately I’ve been doing development with Rhino. Rhino includes a great method to take a java class and make it into a host object one can instantiate in javascript. This method, ScriptableObject.defineClass has the following documentation:,%20java.lang.Class)

    A lot of important details are missing from this (rather long) description of what defineClass does, like what exactly mapInheritence actually does (scroll down for the other forms for even more documentation), or whether the Java constructor is called if a jsConstructor is implemented, or what kind of arguments jsConstructor can take (and especially the special case where you can get access to the constructor function if you provide a jsConstructor with the correct arguments), or the fact that an entirely new object is created, and so the class you are calling defineClass on need not subclass ScriptableObject (or implement the Scriptable interface). These are just a few of the issues in the documentation here.

    So obviously the answer is to read the code! Except not. Looking at the source for ScriptableObject.defineClass will indeed answer some of the above questions, but not all of them, since many of the questions about how stuff gets called are actually only available by digging into the compiler, or the interpreter, or …

    This long winded post, which probably should have just been a blog post on my own blog is just trying to get at the point that while you certainly have the right idea (I don’t need no stinking UML diagrams), there is more to it then just making lean documentation. Some really nice to read documentation that gets at only some of what’s possible isn’t that useful if it doesn’t deal with what you need to know.

  4. 4 successful business March 4, 2013 at 5:39 am

    Thanks a bunch for sharing this with all folks you really realize what you’re talking approximately! Bookmarked. Please also seek advice from my site =). We may have a link change contract among us

  1. 1 Beautifully Lean Documentation Trackback on July 8, 2008 at 7:18 am
  2. 2 Developer Documentation is Useless « // T3chNicaL.LEad Trackback on July 8, 2008 at 8:32 pm
Comments are currently closed.

%d bloggers like this: