"My" Agile Documentation

In the last post I discussed agile programming and noted that I was managing documentation development in my projects the "agile way", even though I did not realize I was doing agile. Here I will summarize briefly some of "my" agile documentation principles.

At least do the Software Requirements Specification

I have written about this before - see here and here, so I will not repeat here. Just to recap. I can accept not writing any product documentation, except the SRS. But this one is not optional.

Start with something

I never thought that writing a full, complete, "perfect" document up-front was feasible. It almost never is. Trying to enforce that is futile. It will stress the team members, take an inordinate amount of time and effort and will become increasingly out of date as the project progresses. Soon, large parts of its content will be obsolete, which means (among others) that we have wasted a great deal of time and money.

Instead, start the document with a minimum and flash it out as you go. In the beginning, most everything is fuzzy and changing, hence, write only more general, more high-level things. As the project progresses, more and more things stabilize. update the docs with these things.

Update on the fly

As the project progresses, no need to go into heavyweight documentation cycles. Just update the documents as soon as new information is identified. Any team members can do that at any time. This makes the project dynamic and makes it easier to develop the documents quickly.

Review, approve, disseminate

Documents are useless if nobody uses them regularly. To make them useful you must make sure that what they say is

• Acceptable - make sure the right people review the documentation and ultimately approve it.
• Known - the best document in the world is useless if people don't use it. Most team members will not if you do not distribute the document formally and make sure people use it.

Keep changes at bay

As I noted in previous posts, unlike the agile principle, I do not "welcome" change. I treat change as unavoidable (don't want to say "evil") in the project. So, I know very well that it will come. However, nobody says you must accept it unquestionably. On the contrary, do question the need for any change. If you can avoid the change, all the better. If not, make sure it's reflected in the documentation, especially, if the documents already cover this topic.

Keep the documentation in sync with the code

Ideally, the documentation should drive the code. In reality a lot of changes are decided and implemented in the code without updating the document. This renders the documents obsolete very fast. Get your team into the habit of updating the documentation at the same time they update the code. It's actually easy because if they keep it up to date all the time, the updates are done in many small steps, rather than major update efforts.

Formatting is not critical

I had cases where we did cut-and-paste directly from emails or from comments in code into the document. This creates a rather sloppy-looking document but it's much better than no document at all and often better than spending all that time/money on high-quality tech-writing. The high quality can follow later. Just make sure that the document is understandable, updated and correct.

Solidify as the release approaches

Changes and updates to the documentation should be harder as the release gets closer. If the project is managed properly, this will be natural. If changes continue to arrive in large quantities even as the release is near, something is wrong. To me, it will indicate that the product is immature and unstable. this will prompt me to consider pushing the release date out. on the other hand, if things are done right, the pressure for changes will go down as the release approaches.

But this is not enough. You (project manager) should implement some process that will intentionally make it harder to get new changes in as the release approaches. People should have stronger and stronger justification to incorporate changes as the release approaches.

Instead, concentrate more on changes to the documentation that do not imply changes to the product (code). Corrections and more details are always good. They improve the documentation without requiring changes in the code.

I can probably think of some more but this is a good start and it's getting late...

-----------------------------------------------------------------------------

Technorati Tags: agile, Project Management, Project Manager, Software Engineering, Software Project Management

Agile Documentation

In a previous post - Waterfall or Agile? Neither, there was a discussion (see the comments) on various points. One of the more interesting points was documentation. I argued against what I thought was the attitude to documentation by the agile community. From my personal experience, people generally interpreted the principle of face-to-face-discussion is preferable to documentation as a license to abandon documentation altogether. Today I still experience this attitude from many professionals, who regard documentation with contempt and rely on agile theory to argue that documentation is not required (even bad) for software development. And that I could not accept. I have seen enough how crazy things are without documentation.

So, I decided to do some further googling to see what people say about documentation and about agile documentation in particular. And I had a pleasant surprise. I came across an excellent white paper by Scott Ambler, titled: Agile Documentation: Strategies for Agile Software Development. It was really a delight to read it. Finally, I saw a very well balanced analysis of the issue of documentation in software development. With very few exceptions, I liked and agreed with everything Scott writes.

In one of the comments in my post above, I said that my goal in the post was to move the agile pendulum a bit back from its extreme swing. From Scott's paper I can see I did not have to do that. The pendulum has already moved back from its extreme position. At least for those professionals who learn agile principles carefully and thoroughly. And now, I think, the pendulum is right where it should be. Not tough, rigid documentation regiment, nor no-documentation at all. Just Agile Documentation. I don't need to repeat hear the principles of agile documentation. Just read Scott's paper above. great read.

If what Scott writes represents the agile community position about proper SW documentation strategy than I am certainly more supportive of agile methods than I was a week ago. The only sad thing is that I find that too many people have not yet realized the correct position on agile on documentation and still think: Agile documentation = no documentation.

And final note to Dave Nicolette - thanks for your very good comment in the post above. I now have a better and more supportive perspective of Agile methodology. It is definitely maturing.

In my next post, I will describe some of my "techniques" for generating SW documentation and show that, at least to some degree, I have been doing agile documentation without realizing it.

----------------------------------------------------------------------------

Technorati Tags: Agile, Waterfall, Project Management, Project Manager, Software Engineering, Software Project Management

Waterfall or Agile? Neither

This is the debate of the century. Waterfall or agile? Everybody has an opinion, emotions run high on both sides of the line and those who don't have an opinion are confused. It looks like everyone must have an opinion to be respectable. OK, I want to be respectable too so here is my opinion.

The first and IMHO, most important point is that the debate makes it look like there are only two alternatives for the "right" software development methodology. If it's not waterfall, then it must be agile. If it's not agile, then it must be waterfall. I say "not so". There are more alternatives. For me it's not waterfall, nor agile. Or should I say "both"? The closest methodology to what I like (and try to do) is Iterative Development. Yes, many of you will say that iterative development is a fundamental component of agile development and they will be right. However, agile development also has several things that I don't like. So, I cannot honestly say that I support agile principles.

Let me say up-front that, in my mind, classical waterfall is completely out of the question. I think that this methodology is so defunct that there is no need for me to explain and justify this position. So, in regards the question "waterfall or agile?", one half of the answer is straight forward: surely not waterfall. But if not waterfall, then what? Well, for me it's not agile either.

Let's cover briefly the major principles of agile and see what I think about them. I will take the principles directly from the original Agile Manifesto:

Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.

This I like. At the end of the day, customer satisfaction is the ultimate goal. I also like the important principle of useful software. With regard to rapid and continuous, I like that too, but remember that it takes two to tango. Meaning, the customer needs to agree and work with us to accept our deliverable and rapidly test and provide feedback. You might be surprised, not all customers will want that.

Which brings me to the an important point. Agile experts agree that full customer cooperation with the project team is essential for the success of the agile methodology. This means that the customer must:

• Thoroughly understand agile techniques.
• Agree to work with the project team by the agile principles.
• Do their part in the "deal".

The above requires significantly more involvement, commitment and resource allocation from the customer. So, not only you need all of the above from your own company, you need the customer to deliver too. Double challenge. My experience:

• Rarely will the customer deliver on the above requirements.
• Most companies that try to implement agile methodology fail to secure the customer's cooperation but still go ahead with the methodology. In this tango you dance alone and the results are accordingly.

Welcome changing requirements, even late in development. Agile processes harness change for the customer's competitive advantage.

I have a problem with this. Change is usually unavoidable in software projects, but welcome? No, I don't think so. This is engineer talk. Project managers call it Scope Creep. I am not saying that change must be blocked "at any price". I am saying that change has to be controlled carefully and allowed only under the right circumstances. Both the project team and the customer (again the customer) have to answer the following questions:

• Is the change really necessary?
• Is it necessary now?
• What will be the benefit?
• What will be the cost?

If the answers show that the change must happen, then so be it. But welcome? Changes are a necessary evil. Sorry, I am the old fashioned type.

Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.

I like that. It's a good technique and it works of you are disciplined enough. Agile is even more strict. It requires timeboxing - even better.

Business people and developers must work together daily throughout the project.

Absolutely. But I think this is true and critical in any methodology. Show me a methodology that will disagree. So, even though this is true, it's not unique to Agile.

Build projects around motivated individuals. Give them the environment and support they need, and trust them to get the job done.

There are two parts here:

• Support the team members. Again, true but universal. Not unique to agile.
• Trust them. Well, where I come from, we had a saying (crude translation): "Respect him and suspect him". As an experienced project manager, I like that better. Not that I think that team members are evil or anything. Just that they are human beings. And that includes me - the project manager - too, of course.

The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.

This one probably irks me most. Not because of what it says but because of what it does not say. What it does not say is: "we hate documentation". Yes, I know. We all hate documentation. More precisely, we hate to write the documents. I have never met a project team member that did not like (and actually appreciated) documentation if:

• It was good quality
• Other people wrote it

It's much easier and more fun to communicate verbally. But verbal communication has serious drawbacks. This is a significant issue that deserves its own post, so I will not go into detail. I will just note here: face-to-face conversation has no records (other then in people's minds) and, therefore, no memory. Again and again, experience shows us that there is no escaping documentation. The big trick is to cleverly decide what documentation, how much? how? etc. But there is no alternative to good documentation. Don't get me wrong, face-to-face conversation is a great and vital means of communication but, sorry, it cannot make documentation unnecessary.

Working software is the primary measure of progress.

I agree assuming the working software does what the customer wants.

Agile processes promote sustainable development. The sponsors, developers, and users should be able to maintain a constant pace indefinitely.

OK, this is not really a guideline. It's more of a promise. I do not have enough statistics to make a determination if this has proven itself. I will be glad if someone can enlighten me on this.

Continuous attention to technical excellence and good design enhances agility.

Again, this is not unique to agile. All methodologies support this, even those that do not call it out specifically.

Simplicity--the art of maximizing the amount of work not done--is essential.

I like this. The KISS principle is a good principle.

The best architectures, requirements, and designs emerge from self-organizing teams.

Here again, I do not have enough insight to make a judgement. Let me know if you have any concrete info about this.

At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.

This is what the PMBOK calls Lessons Learned and is basic project management. It's good and again not unique to agile techniques.

So this is a brief summary on how I feel about agile development. I will sometime write about my own technique for which there is no formal name but I will characterize it as a combination of iterative and flexible waterfall.

Let me know what you think.

-----------------------------------------------------------------

Technorati Tags: agile, waterfall, Project Management, Project Manager, Software Engineering, Software Project Management

-----------------------------------------------------------------