The Sherpa Project

I used to love writing documentation. I was a little different than the average developer I guess. I felt like the more I wrote, the better the documentation was. The height of my excitement was writing a 150+ page functional specification for a product I was doing the architecture and requirements gathering for. I loved sending those huge emails with my document attached. I loved hogging the printer for an hour before a meeting printing out copies for everyone. In short - I guess I just felt like I worked really hard, used words that were hard for others to understand, and had the coolest Visio diagrams. For some reason I really enjoyed that.

I was an idiot.

No one ever read that document and the document was mostly out of date when I was required to “freeze” it. What a waste. Thinking back on it, it would have been a waste if it was half the size. It would have probably been a waste if it was 1/10th of the size.

I decided to completely shun documentation after I realized how much time I wasted (both mine and co-workers) on that document. For a long time I avoided writing documentation at all costs. The great thing about looking for work-arounds from writing documentation was that I found a whole world of great tools that can generate documentation and remove the repetition out of much of the useless documentation that most development shops require.

Like it or not, there are many times that documentation is needed (although a good conversation can replace most of what we normally document).

I recently started a project and took the Agile Modeling approach by Scott Ambler. I can finally say that I’ve found a great middle of the road approach to documentation and modeling. I’ve started giving in and writing documentation (when it’s justified) and I feel like I am producing documents that are valuable.

It’s amazing how readable and useful a document can be when you cut out all the useless shit and put in the stuff that really matters.