Agile Project Documentation

Recently I had to summarize several weeks worth of work and hand sketches into something that is presentable to the client. The first thought is to throw together some screen shots of the application and put that in a document and send it off. The problem with that approach is that there has been a lot of thought on much more then screen shots. Thought has been given to the platform that this could be deployed to, the method for scaling the product, the ability to test the product, day to day management of the product, as well as over all coding.Thought has been given to how the system should be extendable by using interfaces in key points so alternative implementations can be created in the future. The interaction of the software components and the packaging of the software has also been under consideration.

I always have trouble writing this type of document. It takes me longer then I would like and I never feel like the flow and content are up to parr. This time I have spent sometime reflecting on the paper. The paper itself turned out to be around 30 pages long and contained the screen shot section, an architecture section, and a very small sample of what a "Getting Started" page might look like.

I think the problem with my approach is although I preach Agile for software development I never really think of anything else in bite size chunks. For example there has been several times over the last month that I had a clear picture in my mind of how to explain a part of the system. Instead of sitting down and creating a content snippet right then I let the thought evaporate. Unfortunately when I sit down to document the system and all the design the thoughts do not come back into mind so easily. In fact while some of the content comes to mind quickly most of it I am grasping for. That makes one tired.

I am looking into creating Agile documents. Documents with low amount of ceremony so I can keep the personal attachment down. I don't want to create a classic piece of literature i just want to explain the technical merits of a system. I realize to do that I need to improve on my writing abilities.

I have a though about using Google Wave as a snippet holder for both pictures and text. As thoughts come to mind I can create a new entry on the wave. By using a Wave BOT maybe I can have the snippets published to a WIKI or just as a PDF or something... Don't know yet. That is where my thought on this stops.

So why not just use a text editor or any other tool for recording snippets and then use some shell script to publish. That might be a solution tool. Currently I like using Wave because several people can collaborate on the content and it is simple to edit content on a Wave. To me the Wave environment makes since for creating Agile documentation.

The one area that I also need to think about is structure of the content. I would like to have a simple straight forward structure that I use over and over. I know there are thousands of design documents out there but I haven't seen a lot of standardization.

I am looking at a book with the title Agile Software Documentation