Thursday, November 16, 2006

TAGRI (They Aren't Gonna Read It)

Today I read interesting article about the TAGRI (They Aren't Gonna Read It) Principle of Software Development. If you comply with agile everything (which is good for you) you should read this article.

I totally agree with the author as far documentation is concerned. I've wrote with my colleagues System Architecture Specification recently. Document was rather low-level specification (should be high-level ;) and I must confess that I have never ever look at this document again after we base-lined it (BTW. we wrote this document for ourselves - that was the idea). On the other hand what we wrote on our Wiki pages and in Maven-generated documentation is great, fantastic, splendid, etc. Why? Because it is concise, precise and USEFUL.

As the example of WRONG documentation I would recommend you looking at the IBM products documentation e.g. WebSphere MQ. You can find tons of pages of so-called "documentation" on their help pages. Unfortunately when I wanted to install and run their MQ I had no f****ing idea how to do this!!! I spent one whole day on that - it's terrible!!! On the contrary when you want to run ActiveMQ (or TIBCO MQ, or Sonic MQ) it will take you 5 to 30 minutes. That's the difference I think.

Anyway - what I mentioned above are only my modest experiences with documentation. I STRONGLY recommend you reading the article linked at the beginning of this post.


Anonymous said...

Before everything bacame AGILE it was called common sense;). I guess everybody after a software engineering course has an ambition of writing all the documents according to wise templates. He of course fails and then he is ready to write USEFULL documentation.

Przemysław Bielicki said...

Speaking the same language we can say that before Java was C + common sense ;) Actually everything that is written in Java could be written in C, but it isn't.

Agile programming brought unit and integration tests (and many other aspects of software development). It of course came up from common sense but it is somehow structured and described pretty well.

The same is for design patterns. Developers do not invent DPs - they are discovering them. We can say that before Design Patterns: Elements of Reusable Object-Oriented Software book was issued they were called common sense - of course they were but when named and categorized they are simpler to talk about them and easier to understand and use. This makes software development better and more reusable - actually I prefer word extensible to reusable.

Anyway fortunately everything became AGILE not UGLY ;)