Thinking Things Through - How do you use Documentation in Agile Projects?

Question

I am building a very complex application and the scope is getting difficult to keep track of. I have read here and there that in Agile development, you don't want to get bogged down in documentation because the point is to have working software quickly, not lots of documentation.

However, I really enjoy documenting everything I'm doing, figuring I could turn it into a blog article, a nice wiki section, or even a book eventually. I'm usually working by myself or with one or two other people, so there's no big team, and I have to keep a million things in mind at once, so documentation helps me stay focused.

My questions are:

1. How do you - the SO reader - integrate Documentation into your Agile workflow to increase efficiency and comprehension in your projects? By documentation, I'm thinking business-oriented documentation and "how-tos", not source code documentation.

2. How do you integrate this with the other tools you may use to aid in agile development without being repetitive? Some tools might be PivotalTracker, Lighthouse, or even Basecamp (haven't used that one yet for this). So do you enter things into Pivottracker and into the wiki? Stuff like that.

Looking for first hand experiences.

Answer 1

Wiki Wiki - Everything in one place.

We put everything, notes, plans, docs etc into the wiki. If I'm documenting something I write it on the wiki and revisit as often needed. I use one wiki page as a blog, and write things here that I discover or need and then later point to that page or write more docs elsewhere.

Answer 2

I never use a documentation in agile project all we need is a Wiki and also a issue tracker

Answer 3

Hmm, from my personal experience, different projects require different approaches as do people, Doing agile development should not conflict with writing documentation, on the contrary, i think no one would come and say that documentation is a bad idea, the whole point in agile development is when and how you do this.

for me, its something along the lines of:

1. whiteboard meeting with stakeholders and technical staff, in which we identify in a very brief way(only by name and very short description) all of the use-cases/futures
2. analyzing those use-cases and taking about 10% of them(should also be key-issues relating to the system) and writing those 10% in full manner(this is the documentation part)
3. doing the first iteration, in which we write the code for those 10%, including documentation etc..
4. writing another 20% in a full detailed manner, after showing the stakeholders the first 10% and modifying the requirements appropriately..

All of those, during those steps, while writing the full-dressed use-cases, you can and should write documentation.

Answer 4

Based on my experience wiki would be the best choice for the technical part of the documentation. That's the main reason I like Trac: it has it all, both wiki and issue tracker built in with the most beautiful linking scheme I've seen so far.

Any user/admin manual or other non team member targeted documentation I consider it to be a product of the development cycle as well as other products: the program files and the source code. Thus, such documentation, being a part of the project's deliverables should be developed in way similar to the way other deliverables are developed: there should be a source code for the documentation (I recommend Docbook XML or "Help and Manual") and some sort of result of "documentation build", which will be included into the distribution packages.

The source code for the documentation should be managed with the help of a modern SCM (I recommend Subversion), thus, it better be a text-based format. Even plain text files would also do well (for shorter documents).

Writing a user manual (or administrator's manual, or some other dude manual) is a part of the implementation of the features. Documentation can be developed by the same developer, who writes the software source code which implements the feature, or by a dedicated technical writer. Bother ways work well if organized and managed well. It's up to you and your team.

Answer 5

Key documentation features:

• all check-ins had a story reference (so we had traceability back to customer requirements and through to tests) - a process quality auditor told us this is all we needed for ISO900xx (or whatever) given our existing process
• all physical story cards had:
  • a signature of a real customer (required before the story can be scheduled for work)
  • a physical date stamp when completed (done to all completed stories at the end of the iteration)
  • a shiny, pink heart sticker - when a story required help from MIS or the DBA (because we love them and want to draw attention to where we need outside help)

1) How do I integrate Documentation into your Agile workflow to increase efficiency and comprehension in your projects? By documentation, I'm thinking business-oriented documentation and "how-tos", not source code documentation.

I'm thinking of a company I used to work for that had a very short template document for project kick-off meetings. The customer inside our company had to complete one of these documents to initiate a project. The template covered all the things we might need to do. It didn't ask for all the answers or commit people to solutions - it was just to prompt people to think about all the things we know that might affect projects of the kind that we did. It covered things like:

• which functions of our existing code do the clients need?
• what new, custom things does the customer need?
• prompts to get the internal customer to involve all the people that might be needed to get things done - e.g. networking people, the CTO (for expenditures and policies), devs, MIS (for infrastructure changes), the DBA (for corporate reporting-type work because we mostly did our own DBAing inside the apps)
• an idea of timescales for different pieces of the project

We generally tried to do only the documentation that was specifically needed. In particular, we preferred auto-generated technical documentation such as:

• javadoc for publishing APIs
• junit-based tests for descriptions of behaviour of components

Today, I'd include BDD frameworks (e.g. JBehave, Cucumber, Concordion, Fitnesse...) that all help create "executable documents" that describe what the system does in clear, customer-level acceptance tests.

2) How do I integrate this with other tools?

We used a wiki for the bulk of documentation - because of the difficulty of versioning and sharing word documents around the world between teams. (We ran a follow-the-sun distributed XP model with three different teams sharing a codebase, building a closely related suite of products.)

We planned projects and iterations on index cards in the old-fashioned XP way, although our heads of development recorded estimates and summaries that were published for people who wanted a quick report of the current state.

Summary

• We tried to minimise the amount of documentation - by focusing on what's needed and by whom rather than writing big, weighty tomes for "general use".
• We preferred automated technical documentation because of the rate of change of our code and the cost of documentation work - which is taken out of normal dev time.
• We preferred manual, index card-based planning because it encourages more collaborative team behaviour, and because it's simpler and faster - even though the heads of dev had to write up regular summaries.

If you focus on simplicity and concreteness, it's amazing how little electronic documentation you really need - especially management documentation.