"Thoughtful" Agile Isn't

I was exploring the idea of co-teaching with someone I met several years ago. He now teaches at a local university and no longer works in industry. He wants to teach some kind of agile workshop with me.

He said, “I want to teach a thoughtful kind of agile. The kind where you work in timeboxes, but you still have requirements documents and functional design specs before writing any code.”

I replied, “That's not agile unless the customer is demanding the specs as output. Are they?”

“No. But it's impossible to do good software development without specs. I have xx years of experience that says so.”

“Your years of experience in a serial lifecycle don't translate to agile, or even to an iterative or incremental lifecycle. Can you even imagine a project where you don't need specs?”


I tried again. “Have you worked on an agile project?”

“No, I was planning on talking to people who had worked on agile projects to see what it was like.”

I was angry and frustrated at spending time with this person. I declined the opportunity to co-teach. Here's someone who's never been on an agile project, who's never tried another path, who wants to teach “thoughtful” agile–and pass it off as the real thing.

Maybe this isn't criminal, but it's darn close.

If you're looking for agile training, ask the instructor about his or her experience doing, coaching, managing, whatever agile projects. Don't blindly look for certification or a syllabus you like (although a good syllabus is helpful). Ask about experience. If you're learning how to pair, how can you learn from someone who hasn't and doesn't know the pitfalls? If you're learning how to use continuous integration or timeboxes, how can you learn from someone who's never used CI or timeboxes?

I don't buy the “I can hear about it and teach it” argument; that's what leads to “People who can, do; people who can't, teach” maxim.

Thoughtful agile is when you choose an agile lifecycle or set of practices, and follow them to the letter until you succeed. You inspect and adapt as you go. After you've succeeded, then, only then, can you change things to make more sense. (Read Ron Jeffries' article We Tried Baseball and It Didn't Work.) But you can't change agile until you know how to make it work. And, if you can't do agile, have never tried agile, and have no real idea what agile is, you can't teach it.

Just had to get that off my chest.

P.S. Added the before writing any code to make it clearer what I objected to.

12 thoughts on “"Thoughtful" Agile Isn't”

  1. Specs and design documents are rarely needed by the customer. But the customer may not need source code either. Why bother with source code when machine code works fine?

    If you are dropped into a project where the original developers wrote no design documents rationalizing decisions, and no specifications or user documentation, it is difficult to get up to speed. It is not for the customers, it is for the developers who come later, or the original developers, after they have forgotten how to unravel their ravioli.

  2. “Why bother with source code when machine code works fine?”

    you answered your own question. source code is for developers. machine code is for machines.

    specs are usually wrong by the time the code is being written. give me a 30 minute run down of the requirements and the design thus far by all means, but a spec is meaningless for a new developer on an existing project.

    if you expect your coders to just churn out – without alteration – a specification handed down from high by the lead designer you ain’t anywhere near agile.

  3. Frank, I’ve been dropped on many legacy projects in my career, some of which had years of history and some only a few months. I have never yet found design documents that were helpful.

    What I have found helpful is well-written code that tries to express the important ideas. I’ve found unit tests that describe the usage of code to be helpful.

    I’ve found comments in code that were interesting from a historical perspective, but did not represent what the code actually did. I’ve found comments that tried to explain the language that was used to write the code.

    And one time when I was working on a NASA project, I was unsure of a small detail in the algorithm I was implementing. I asked around (as I was working from verbal specs) and was told to consult the Design Specs. I asked around some more, and found a four-inch binder with these specs. As I searched through these documents for the information, I noticed that it had been signed by high-ranking executives and civil servants a couple years before. I also noticed large passages of boilerplate that contained no information. And I noticed some references to an older project, apparently the one where some of the boilerplate was lifted. Finally I found the place where my algorithm was discussed. The item about which I was unsure was specifically mentioned: as TBD.

    Good specs are incredibly hard to write. The deck is stacked against you. It’s hard to guess the mindset of the person who will be reading them, because things change so quickly. It’s hard to get them right without the confirmation of passing tests against running code. And then there’s the problem of being both a good tech writer and a good designer. (I have an undergraduate degree in English, but that doesn’t make me a good tech writer.)

    I can eventually work out pretty much any mess, but I’d rather follow a developer who doesn’t create pasta of their code in the first place. If you want to spend extra effort, that’s the best place to spend it.

  4. abby, the hacker chick blog

    Go, Johanna! 🙂

    I decided to go back to school for a masters in software engineering a few years ago and I was floored by how out-dated all of the ideas were. Forget agile! Forget iterative! Even RUP was considered a little too “weird” by most of the professors.

    At the end, rather than a thesis, we had to develop real software for a real customer. Part of the assignment was to pick our own process. After finishing all 12 classes with a 4.0 GPA, I almost failed out and didn’t get the degree because apparently “pick your process” meant we could pick any flavor of waterfall we wanted. Iterative was bad – forget coding, how could we do any design before all the requirements had been nailed down??


  5. Design documents and specifications are part of the source base. They are not a separate breed. All human readable documents are artifacts required for human developers; only the machine code is needed by the customer.

    I have witnessed plenty of documentation abuse. I have seen specs large enough for a monstrous five year project, which was expected to be completed in 3 months. I understand perfectly the points made by agile proponents.

    This doesn’t mean specifications and design documents are all bad. The proportion of design and specification, to programming, should be proportional to the size or complexity of the application. Some types of applications, for example where human safety is involved, require precise axiomatic specifications, ideally specifications that can validate the code.

    On the other side I have seen projects with no documentation. The code was poorly written. In this case, documentation, out of date, anything at all, would be useful. When the original developers are gone, it becomes a process of reverse engineering, which is rarely a good investment.

    Specifications of invariants, in the form of a document or better still, in the form of design-by-contract invariants, preconditions, and postconditions, are the most useful form of specifications I have used. They are part of the source code but often easier to understand when summarized in a separate document.

    Operational tests are not as useful, as they do not state axioms that apply in all circumstances.

    Without an explanation of rationales, usually provided by a design document (but can be in comments), later developers, or even the original developers over time, may reproduce mistakes. Reverse engineering the decision making process can arrive at incorrect conclusions.

    There is nothing in an agile development process that prohibits design documents or specifications. These can be part of an agile, iterative development process, just like any other development process. People associate heavy documentation with the opposite of agile, because that is where they see the worst abuses.

    Suppose I need to write software that communicates with a hardware device. Would that software use a hardware specification? Most likely. And standardized software interfaces (operating systems, communication protocols) also need specifications. We cannot escape specifications. I was not referring to giant UI requirements documents written during a waterfall development process.

  6. I would add that for some software is never fully understood without specifications. For example, the documentation for a public software library ideally has a complete explanation of the behavior of each method in the library, under all circumstances, including the argument preconditions, the method post conditions (results), and exceptions thrown. This is a form of specification used every day by nearly every developer on the planet.

    A language grammar is a type of specification. From the grammar, we can predict precisely how the language will parse an input string. This is the best type of specification because we can usually compile the grammar a well.

    A finite state machine diagram is a visual specification. These are commonly used in designing embedded software applications. Sometimes software is written without any code, only diagrams (simulink). You can say the diagram is a type of code, but it is the same type of diagram we would use for documentation.

  7. Scot wrote, “specs are usually wrong by the time the code is being written.”

    Scot summarized the best argument against specifications and design documents. Lets assume these duplicate some of the same information in the source code. When the source code changes, the specs are out of date. No one wants to keep two things up to date, when only one thing (object code, from source code) is a deliverable.

    Is it true that the specifications and design documents duplicate information? Is is worthwhile to keep them up to date? For many small, application level software projects, it may not be worthwhile.

    From that, we cannot conlude all specications and design documents are a waste of time.

    A specification does not duplicate information. A formal specication is an axiomatic description of software; source code and tests are operational descriptions. They complement one another. With good language support (Spec#, Eiffel) a specication can prove the correctness of the source code.

    A design document does not duplicate information either. It provides the rationale behind design decisions. This can be embedded in the source code as comments. It is impossible to embed this information without comments.

    What can we do with a specification, that we cannot do with source code? For one thing, it is easier to create an alternative implementation using a specification, than using only source code. Given only source code, we first have to reverse engineer a specification (what is it supposed to do), then create an alternative implementation. whether that process is purely mental or involves writing a real specification, it must be done at some level, and it is a waste of time, especially when the developer must unravel ravioli.

    Often a specification is more important than the source code. The definition of any type of software standard, including standards produced by the W3C, is a specification. These are more important than any source code implementation, as they allow many people to create alternative implementations.

    Avoiding all documentation is not the solution to the problem of over-documentation and over-specification. One part of the solution is to determine how to make the specification part of the source code, as in Spec#, Eiffel, Antlr, or anthing that makes use of specification for a purpose. The second part of the solution is to document in proportion to need.

    What would life be like without specifications?

    Your car, airplane, and medical equipment would not use a computer. A specification of invariants protecting human life is critical.

    You would not be using a web browser, or any software based on web standards.

    You would not be using a computer at all. Commodity hardware Would not exist without software and hardware standards specifications.

    Your bank would transfer money to another bank with an armored car. Records would be kept on paper. Pneumatic tube lines transferring letters would be useful as an alternative to email.

    You would not be using electronics. Even analog electronic component vendors provide a “spec sheet”, for standardized, reliable behavior is needed for components in electronic designs, just as it is needed for components in software designs.

  8. To me, the post is about someone wanting to teach a course without any experience in the subject matter. Of course all teachers should have experience in the subject matter. That, however, would soon lead to the closure of almost all colleges and high schools.

    How many of us had a high school English teacher who had published a novel? Well, how can they aspire to teach writing without that experience?

    This is a tough situation.

  9. Thierry Thelliez

    Isn’t the issue wide spread in our industry? How many consultants have I seen selling a concept or technology without having the experience to back their claims?

    We have all seen the fresh readers of ‘Java in 10 lessons’ optimistically jumping on a large piece of code.

    I think that with the push of Agile ideas, it has been even worse. I am not questioning the added value of an Agile approach. However, in the absence of metrics and/or any curriculum, I have seen many claims that cannot be verified and claims by individuals who are lacking real understanding and are actually hurting the concept they are trying to push.

    On the other hand, early adopters and evangelists cannot have much experience.

    I usually insist to get contextual information before listening to a presentation: are you using this idea/concept/technology in a production -like environment? For how long?…


  10. Pingback:   Christian Bale And Matthew McConaughey Teach Product Managers About Agile Development by ChristopherCummings.com

Leave a Comment

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: