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.

It never ceases to amaze me how complicated we tend to make things. It’s mostly learned behavior or a desire to implement the latest and greatest pattern that we’ve read about. I think that over-engineering is really one of the biggest problems that our industry faces. It’s prominent with developers, but it’s also common throughout all ranks and positions in our industry.

Unfortunately, this adds up to massive amounts of waste. We write a ton of features that never get used, we come up with really cool implementations that are really hard to maintain, and we spend a lot of time worrying about how to increase the speed of our app by a few milliseconds when it’s likely that the performance is sufficient. We think we have to concurrently handle China when our app will probably never have to concurrently handle the number of people that live on our block. The entire time that we are doing this, we are likely wasting the time and money of our clients or our organizations.

The next time you’re at work take a few minutes and notice the interaction and thoughts of the development, management, and business teams. Is everyone focused on delivering value as soon as possible to their clients? Do the daily discussions revolve more around features or more around layers? Does everyone believe and think about the intended value of the system that is being worked on, or are they just focused on writing a good data access layer or a scalable middle tier?

Imagine what would happen if you did the simplest thing that could possibly work. Imagine that you implemented your application in vertical slices of business needs versus horizontal slices of technical needs. Imagine if you allowed the architecture to evolve with the code and you let the system emerge rather than spent the time upfront to diagram out every possible scenario. It all sounds so simple – but as industry we have a lot of unlearning to do.