Developers Aren't Gonna Read It

Good try with the marketing -- but I kinda expected you to tell me in plain english somewhere near the top or under the heading "Developers Aren't Gonna Read It" exactly what It is and why I ought to read it. But, because you can't seem to put that on paper, no, I am not going to read it. I think most developers like hearing about new perspectives and many might have been blown away by your article. But, please take a queue not from marketers with strategies like naming an article or snub "Developers Aren't Gonna Read It" but rather from writers who know how to capture the attention of their audiences. You know, I've never visited whatif or whatnow or whatever that stupid website is that keeps advertising on television and has a significantly lower page rank and Alexa rating that my website. Gimmicks don't work. Give me content or give me death.

If they aren't going to read it, you shouldn't be employing them. Much of what you say here is a question of professionalism. If you want a well designed house, you don't hire architects who aren't going to read your specification; if you want a well designed car, you don't hire design engineers who ignore your specification; et cetera.

On well run teams, specifications are required reading, time is set aside for reading, and the engineer is quizzed to make sure not only that they've read, but also that they've, understood, the documentation. You can enforce reading. Developers are gonna read it, if you make them, and the product will be infinitely better for doing so. The more you allow young, unsophisticated workers in any field to get away with skipping their work, they will. The purpose of management is to prevent these sorts of shenanigans.

Developers want to work in healthy, profitable companies with reliable product. All you have to do is create an environment where they don't make these careless, sloppy mistakes.

You might want to start by reading about PSP/TSP and the Capability Maturity Model. They'll help you understand how to prevent this sort of problem.

They are going to read it. You just have to make them understand that.

(Incidentally, KISS stands for "keep it simple, stupid". Stupid refers to the person hearing the term. Swapping those words changes the meaning. Don't do that.)

... is that the developers understand what is needed from the system they develop. And reading a written spec is hardly the best way to get that understanding into the developers' heads.

You're absolutely right in that live one on one interaction with the user is essential - but for different reasons. It's an opportunity for the developer to confirm their understanding of the written requirements, both up front, and ongoing. I'd be interested in understanding how you handled scenarios where most, but not all, of the requirements were not met because the document was not read (we're human, it happens!).

Now we face a situation, where a customer has a huge, mission-critical system without any documentation and the system is about to crash in any minute. They asked for help but without detailed use cases, specification of the aging system, how would anybody be able to fix issues or migrate to a new version, if nobody knows exactly, what the system is going to do?

That's not true, in my experience. When the customer and the spec disagree, it's the customer who is right, and the spec is wrong. To build the right system, you need good, regular feedback from the customer.

stands for "keep it simple, stupid" not "keep it simple stupid"

Verbal communication is great until that person is hit by a bus and no one has thier vision any longer.

So you think that if your visionary is hit by bus, you are safe because he wrote his vision down beforehand? I don't think so - you'd better off finding a new visionary with his own vision (who best was in close contact with the old visionary).

Having error codes and validation in unit test is wonderful but have you ever meet a programmer with proper english. Someone needs to write done what they would like the validation messages to say and they certainly do not want to work in source code.

Yes, I've actually met programmers with proper English. Anyway, if someone else needs to write validation messages or something, let them do it in property files, or their automated tests - much more effective than documentation. (If you are working with developers without proper English, do you really trust them to correctly copy those messages from the documentation to the code?)

During a release cycle of a product your need to have clear requirements going into the release.

Yes. And you need to know whether the requirements have actually been met, which is best accomplished by having the requirements be executable. In Agile Software Development we typically call those executable requirements "Acceptance Tests".

During the next 10 weeks or however long the release cycle is requirements may change and that change needs to be reflected in the software. It is not neccessary to go back and update the original requirements, design documents and specification.

In fact, it is highly desirable to change the executable requirements specification, so that it still can be used to communicate what is actually wanted, and to check whether the system actually does what is wanted.

After a release the end result of the release needs to be documented so that there is a baseline for the next release.

Yes. You definitely don't want that future releases break already existing functionality. Acceptance Tests are good for this, too.

Note! I am talking about projects that have fewer thatn 10 people working on them and communication is good. If you are working on a product like Windows were one small change could effect other groups then CMMI and full design reviews and documentation are essential.

Are they? I'm not so sure, but I don't have any experience with such big projects. Others have: http://www.jeckstein.com/agilebook/

CMM Level 3 states that a Softwware house should have a methodology to make processes stable,repeatable and managable.Otherwise its plum pudding model.A plum can be anywhere in the pudding.

In Opensource technologies, documantation is crucial as the the field is rapidly changing and as many become novice now and then before they master the new technologies.

The aim is to make money.The faster your development the more you deliver.Time spent trying to google if there exits someone who tried to do what you are stuck with,is money waisted.

Even Forums imply document something!

So there is a solid business case for Documantation especialy for novice developers and for avoiding legacy systems of our times.