Home > management > Working Software, Working Documents

Working Software, Working Documents

Documentation is a love letter that you write to your future self – Damian Conway

The agile software development community rightly says that the best measure of progress is demonstrate-able working software that is delivered incrementally and frequently to customers for their viewing and using pleasure. For the most part, and for good reasons based on historical evidence, agile proponents eschew documentation. Nevertheless, big bureaucratic customers like national and state governments often, very often, require and expect comprehensive documentation from their vendors. Thus, zealot agilist juntas essentially ignore the requirements of a large and deep-pocketed customer base.

It’s software development, not documentation development – Scott Ambler

What if we can bring big, stodgy, conservative, and sometimes-paranoid customers halfway? Why not try to convince them of the merits of delivering frequent and incrementally improving requirements, design, construction, and user documents along with the working software builds? If we pay as we go, incrementally doing a little documentation, doing a little software coding, and doing a little testing instead of piling on the documentation up front or frantically kludging the documents together after the fact, wouldn’t the end result would turn out better?

Useful Docs

A consequence of generating crappy documentation for big, long-lived systems is the high cost of downstream maintenance. Dumping hundreds of thousands of lines of code onto the maintenance team without handing them synchronized blueprints is an irresponsible act of disrespect to both the team and the company. Without being able to see the forest for the trees, maintenance teams, which are usually comprised of young and impressionable developers, get frustrated and inject kludged up implementations of new features and bug fixes into the product. Bad habits are formed, new product versions get delivered later and later, and maintenance costs grow higher and higher. Bummer.

Poop Docs

  1. Ray
    October 29, 2009 at 7:25 am

    Some customers have a rigid template for the documentation that must be followed. Along with a rigid schedule that follows a waterfall type of pattern. Then you take the job or not.

    Also what one developer thinks as good documentation for the maintenance developer may leave a lot out especially in projects that are over designed.

    • October 29, 2009 at 1:28 pm

      The idea still stands; rigid templates or not, waterfall or not. Here’s the snippet I want to repeat:

      “What if we can bring big, stodgy, conservative, and sometimes-paranoid customers halfway? Why not try to convince them…”

      Alas, who would be the one(s) to try and change the ancient and rigid system in place? Who’s the “we” I mention? Certainly not me, and it looks like it’s not you either :^)

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: