Thursday, December 04, 2008

Developers Aren't Gonna Read It

Picture courtesy of austinevan@flickr
Developers are the customers - from time to time. They are the customers for product definition/specification team that is preparing technical specification documents. It doesn't really matter whether you work in an agile or non-agile environment - I'm sure you have some technical documentation and the main goal of it is to answer developers' questions on technical issues (e.g. how to configure some components to work with others, how to map fields from GUI forms to XML message, etc.) It also helps test or QA team to prepare acceptance tests and to verify whether what developers implemented is what was specified (I know it stinks a bit the waterfall but stay tuned - I will say something about agile documentation soon).

I would suggest you reading an article on TAGRI (They Aren't Gonna Read It) by Scott W. Ambler - it's really great. And in my post I'm going to give you real-life example from what I experienced regarding documentation. I will share with you my opinions of what kind of documentation sucks and what documents are really cool and useful (btw. my dream documentation is the one with which I'm able to find accurate information of my interest quickly and be able to put this information into my head in less than 10 minutes - the picture you see is a total contradiction of my dream - it's a waterfall process).

Developers won't read it

At the beginning of the project I met with the specification creators in order to discuss what we are going to deliver. They described me the project goals, business value and the requirements, of course. They also showed me two big books (sorry, specification docs) with around 300 pages in total. And the project was quite simple - it was basic CRU (Create, Read, Update) with one type of objects to be stored and queried. Believe me - the system was simple.

I was responsible for the web UI part of this system (100 pages) but had to understand also how the backend works (200 pages). Wow! That's a lot of, for a simple system, to read - imagine how much time you need to read this. And it's nothing comparing to how much time and effort it cost to produce it - and you still have no single line of code working.

So, did I read the documentation? I didn't.

I didn't have to because I preferred direct communication with the guys who know the system throughout. I didn't have to read the documentation because the guy who specified the GUI prepared screen mockups and I knew exactly how the pages should look like. And I didn't need 100 pages of documentation for it. I just needed couple of screen mockups - it was enough for me to deliver the software.

Tests and examples are the best documentation ever

And they are not only the best documentation - they also define a design of the system to great extent. When I was integrating UI forms with the XML to the backend I was still not referring to any documentation. I just asked guys responsible for specification and preparation of tests to give me example messages (requests and responses). I got what I needed and basing on the examples I was able to integrate UI with the backend - simple. Here I will give kudos for the specification that explained how to map UI form fields into XML message (XML schema was not self-explanatory in many places e.g. I could store the phone number in different XML tags - I had to know which one I should fill). I also used a piece of documentation that explained what should be the format of input data - I had to validate user's input somehow. But that was all I needed - I used 5% (roughly) of the overall documentation stack.

KISS (Keep It Stupid Simple)

In that simple project we had three different documents and I was finding discrepancies between them almost every day - yes, some of the fields, data types, etc. were specified in all three documents (often differently). The part developed by me was quite resistant to this because I was still keeping my one source of information. If I didn't know something I just asked specification team - I wasn't looking for the answer in the documentation because it would take more time and it appeared that I was asking questions that were mostly not covered by the documentation. Again, verbal communication was the best choice for me - I was able to fix some mistakes in the documentation on the fly - because I reported every technical problem I had to those guys - they were adjusting details according to technical constraints.

To summarize this point - keep it simple. Have one source of information and you will win. I do - every time I follow this rule.

Not all documentation sucks

That's true - some level of documentation is necessary, as I showed it before. Some mappings are sometimes required, list of required fields, error codes, etc. Many of this can and should be covered by unit tests and automated GUI tests - but it's pretty hard to record GUI tests not having it. Usually in waterfall-like process documentation is considered as a good - very important good. I don't understand why? It doesn't represent any business value for the customer (except the user's guides) but a lot of people value documentation more than the working software. I think this is the reason they fail so often.

In my opinion the best documentation is the one that is very easily changeable. For example Word documents stored in Lotus Notes folders is a bad idea. Developers cannot easily change or even comment the specification/documentation - they should. I often faced the problem that I saw something really really stupid in the docs and I wanted to change it but I wasn't able. Wiki is the best option here - it's easily searchable (through many projects) and changeable. And if you want to have a Word doc - your business - just export the page to the format of your choice.


My main recommendation is to communicate verbally with people who know your product as often as you need; have one source of information - you will not be surprised by different requirements for the same thing; start with unit testing your code and keep your UI tests up to date; automate as many acceptance tests as possible - consult the results with customers (or customer proxies).

I'm not going to copy-paste the whole article but I totally support the Solution part of TAGRI article - I strongly recommend you reading it. I have nothing more to add.

What is your experience with documentation? Do you read huge stacks of papers your team lead gives you? What is the value of the documentation? Please, share your opinions here.

Originally published on

No comments: