The Agile process: how and what should be documented?

Question

A while ago the company I work for had outsourced a development project to a third party. They employed agile practices in developing the solution. However when asked for documentation they would just say it was required as it was incorporated in a wiki or as part of their sprints.

They did leave at the completion of the project, with all but one of the project team. The project wiki site has now been closed down once the yearly subscription was due.

When they left they took most of the knowledge and understanding of what was developed with them.

So I do have 2 main questions;

1. Is this normal for agile or just an excuse for not wanting to write it?
2. What are the industry norm for documentation in agile projects to record development requirements, designs, key decisions and context?

Answer 1

Did they leave you a set of TDD Tests, Acceptance Tests, or other Unit Tests? They do a good job of documenting how an application works and is expected to work, as well as providing a sample implementation of how to use what was developed.

Answer 2

Is this normal for agile or just an excuse for not wanting to write it?

My theory is that it's why agile spread so fast, especially scrum. I've seen too many team wanting agile to protect themselves (instead of the whole company). The problem is that in many case, the methodology is used against them by management (because they want to protect themselves too!).

Does this means agile doesn't work at all? Of course not, this just means that agile helps you to solve few common problems, but you are still in charge of all the others. And in many case agile is just not suitable for that team in that company.

What are the industry norm for documentation in agile projects to record development requirements, designs, key decisions and context?

To be short:

The team should define how much documentation they need

They know the domain, they are the experts and more importantly they build the thing!

That's what Working software over comprehensive documentation in the Agile Manifesto means.

Answer 3

While I'm not an Agile expert by any means, here is my attempt at an answer:

1. Was there a story/requirement asking for specific documentation? If not, then this is part of the problem as you get what is requested to some extent. It is an excuse and I could wonder what you mean by "normal" here. Is it just a majority of those following Agile principles that makes something normal or is it part of the overall process that should be expected? Those are the two views I could see for it. EDIT: I doubt there is anything the majority of teams do that is the same when it comes to documentation, but that is a guess on my part.

2. A couple links that may be of interest, is about the best I could do on this:

   • Best Practices for Agile/Lean Documentation
   • Agile and Technical Documentation

Agile has some specific points in the manifesto, where I'd point out this one along with the note:

Working software over comprehensive documentation

That is, while there is value in the items on the right, we value the items on the left more.

Answer 4

They're just horrible. I don't believe agile means no documentation at all. They should have at least kept track of the application description. Getting an export of their wiki would have been nice or allowed someone else to pick up the service fee.

It may not be as detailed as some attempt. The theory is, when in a time-crunch, the specs no longer match the code anyway. So you have enough documentation to write the code and not try to define it in detail (Sort of like writing the code in some pseudo-verbalized-text/diagram-code and then in the actual code.).

Answer 5

Your problem has nothing to do with Agile. They should have produced the documentation that you asked for. The project was poorly managed.

Answer 6

There should be some description of the features, user stories, and test cases somewhere, at minimum. IT might be in ReadMe files in the projects, it might be in the source-code comments, it might be in design documents; it might be all of the above... or it might be MIA!

Answer 7

In my experience there are always a lot of people demanding documentation (I've been one of them) but in practice noone really has time or desire to create them. Occasionally there are efforts, but the documentation created typically gets outdated very quick and gets out of sync with the real functioning of the system. This leads to a situation where even if you do have documentation noone really bothers checking it cause they simply don't trust it's accuracy.

For real accuracy and reliable information it pretty much comes down to being able to read code and tests. A customer wanting to (re)discover what his system does can always interview and query a programmer who can then present (with some investigation) facts about the system.

Creating good documentation is -not- trivial and can be quite costly. Secondly one could wonder about the audience, who is the documentation for and what is it intended to provide?