Agile Software Development - Comments

K.I.S.S.

James — Fri, 21 Nov 2008 16:47:38 -0800

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

Re: You'll need it in the future

Ilja Preuss — Fri, 21 Nov 2008 15:27:31 -0800

Have you ever seen a spec that actually described what the system really did? I haven't. What I have seen are specs that ambiguos, full of holes, inconsistent, illogical, or simply plain out of sync with what actually was implemented.

So, if I was asked for help by that customer, I'd like to have two things to help me know what the system is supposed to do: access to the users and domain experts of the system, and an extensive suite of acceptance and unit tests.

"But the final say on the rules is the spec."

Ilja Preuss — Fri, 21 Nov 2008 15:21:24 -0800

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.

First of all I didn't write

pbielicki — Fri, 21 Nov 2008 10:37:25 -0800

First of all I didn't write that you should not document AT ALL. Please read my post carefully.
Second of all I've never met a company who had a mission critical system without having specialists who know the system pretty well and who can help other team(s) (probably taking over the project). But if it happens - how can this system be a mission critical?
As I wrote in my post some level of documentation is useful (it also depends on the system) but the more is in the people's heads the better (see "pair programming" and "collective code/system ownership" from XP).

Again - the best documentation for big and critical system I've ever found was a Wiki page with names and phone numbers.

Thanks for your comment.

You'll need it in the future

Model Man — Fri, 21 Nov 2008 04:36:06 -0800

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?

Heh - It was quick and essential

Sebo — Fri, 21 Nov 2008 03:34:20 -0800

Thx, for Your work.

I've found Agile projects to generate more documentation

Handly Cameron — Fri, 21 Nov 2008 02:45:43 -0800

Our Agile projects have generated much more documentation than our non-Agile projects. Even better, it has been useful documentation with a minimum of effort.

How's that you ask?

We don't spend a lot of time on up front documentation, just as you recommend above. We have found that the non-Agile projects spend a ton of time here and in the end, usually don't produce all that much documentation anyway.

Where the Agile projects excel is in status reporting. While the non-Agile project manager spends several hours each week to gather data and write and essay on how he feels the project is going, the Agile PM is able to quickly report what we planned to do this iteration, how much we have done, and what is planned for the next iteration. It is also easy to include pretty burndown charts, test status, and other information. When shown an example, one non-Agile PM commented "We could never have that much detail in our reports!"

In the end, the Agile status reports are about 4 times longer than the non-Agile ones and serve very well to inform stakeholders and keep them from interrupting work because we have already answered their questions.

Stating the obvious

Anonymous — Thu, 20 Nov 2008 17:12:56 -0800

rather like a lot of documentation.
hneh.

The ranking criteria is

Anonymous — Thu, 20 Nov 2008 14:52:36 -0800

The ranking criteria is terribly flaw. The listed book are definitely not the best books in software engineering at all.

You're absolutely right in

johnw — Thu, 20 Nov 2008 14:31:40 -0800

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!).

I agree with A Dissenting Opinion

paperdummy — Thu, 20 Nov 2008 13:57:49 -0800

You can make something that works without reading the spec. But you can't make something that conforms to the spec without reading the spec. You are talking about inductive logic--inferring a rule from examples. But the final say on the rules is the spec. If you infer incorrectly, you will deviate from the spec.

What you need is a well-written spec and concise, well-organized documentation The reason TAGRI is because most documentation is terrible.

(FULL DISCLOSURE: I am a tech writer)

What's really necessary...

Ilja Preuss — Thu, 20 Nov 2008 10:58:47 -0800

... 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.

What do you call

pbielicki — Thu, 20 Nov 2008 10:48:10 -0800

What do you call professionalism? "Developers are gonna read it, if you make them" - who are you? A dictator? What is your goal? I thought the goal of the software organization (besides earning money) is to produce good quality software not reading documentation. Yes - some documents are useful - mostly those that tell who to ask about the details. Documentation should help you achieving the goal - it is not the goal itself.
And BTW. I just reminded myself the first law of documentation by Robert C. Martin: "Don't produce any documentation unless its need is immediate and significant".

A dissenting opinion

John Haugeland — Thu, 20 Nov 2008 08:57:46 -0800

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.)

I Agree

Steph — Thu, 20 Nov 2008 08:07:42 -0800

It's more than that, often trying to decipher the requirements documentation is much more complex than just reading 200 pages. Some requirements documents I read looked they were intentionally encrypted.

Like you say, it's much much easier to just ask (minutes versus hours to days deciphering the meaning of the document which is often unclear in the first place), and it's always right when you ask whereas the documentation can be out of date.

Keep it simple :)