Monday, August 31, 2009

Quote Series Part 7 - Philosophy

This is part seven of the series, to see what this series is about, click here.

Quotes on "Philosophy"
...initiating requires a willingness to look foolish, stupid, or uninformed. To initiate great things, you must truly not give a damn about what people think about you. - Seth Godin (Tribes book)
what you call things and their meaning matters cuz it sticks in people's mind - Twitterstream from Lean Kanban 2009 conference
No good idea can be judged by the number of people that get it - Ron Jeffries
Learning faster than our competitor is our only sustainable competitive advantage. - Denise Caron
Change happens fast, our competitors will not wait for us to get ready. - Denise Caron
Self-organize... don't wait to be told, be accountable and stride forward. Self correct! - Denise Caron
Satisfaction comes from closure- open-ended tasks can't be closed - ObjectMentor coach
Managing the project is MANAGEMENT'S responsibility... do the best you can with what you know now and program as though you have time to do a good job. - ObjectMentor coach
If you deliver every day, then no deadlines are special (or scary). - ObjectMentor coach
If it doesn’t hurt, then you’re probably not changing enough. - J. B. Rainsberger
If you just do the same things, only faster, then you’re missing the point. - J. B. Rainsberger

Note: where I can, I've credited or linked the source of the quote. Finding the source of a quote is like chasing a ghost. When a mentor says something witty, you might not know they are quoting someone else. If you are aware of a more appropriate source for any quote, PLEASE put a comment on the post and I'll do what I can to validate this. I mean no disrespect to anyone. I believe the risk of incorrect citings is outweighed by the value of sharing these wonderful nuggets.

Friday, August 28, 2009

Quote Series Part 6 - People

This is part six of the series, to see what this series is about, click here.

Quotes on "People"
If you don't make mistakes, you are not working on hard enough problems - Frank Wilczek
Open yourself to critics and take your capabilities to new heights. - Denise Caron
If you goof, apologize. If you apologize, mean it. - Seth Godin
If you want something to happen your way, try asking instead of demanding. - Seth Godin
If you’re getting feedback, realize that the person must care a lot to have sent it. - Seth Godin
Anyone who uses the term “resource” when referencing people has to put $1 in the “inappropriate comment” jar! - unknown
No matter the circumstances you can always improve. You can always start improving with yourself. You can always start improving today. - Kent Beck
A tool is nothing without a skilled artisan to handle it. - unknown
Don't inflict change on people. - J.B. Rainsberger
A dead scrum master is no good to anyone. - unknown

Note: where I can, I've credited or linked the source of the quote. Finding the source of a quote is like chasing a ghost. When a mentor says something witty, you might not know they are quoting someone else. If you are aware of a more appropriate source for any quote, PLEASE put a comment on the post and I'll do what I can to validate this. I mean no disrespect to anyone. I believe the risk of incorrect citings is outweighed by the value of sharing these wonderful nuggets.

Thursday, August 27, 2009

Does generalized roles mean a team of equals?

A very interesting discussion on LinkedIn got me to thinking...

If a Scrum/XP team adopts pair programming...
and everyone should be able to pick up anything...
and anyone should be able to test or fix the build...

does that mean there is no longer a need for team lead? tech lead?

Hmmm...

Interesting discussion.

My thoughts:
...every Agile/Scrum team I've been on has had "leaders" that fill the roles of project or tech lead. In my mind, the advantage of agile is not to normalize the team to a bunch of equals, but to reduce the distance between the outliers. Keeping some diversity in the team is critical to team wisdom (read Wisdom of Crowds).

Feel free to join in the discussion.

Wednesday, August 26, 2009

Quote Series Part 5 - Code

This is part five of the series, to see what this series is about, click here.

Quotes on "Code"
Code degrades naturally, it needs refactoring constantly - ObjectMentor coach
Treat the system as a growing organism... failing tests equal the need for a behavior modification - ObjectMentor coach
Always check it in in a better state than you checked it out. - ObjectMentor coach
Don't let code sleep - things happen while you're asleep. (tests must pass on "sleeping" code) - Tim Ottinger
Switch pairs whenever you need to, it is not an insult but a way towards knowledge transfer and efficiency. - ObjectMentor coach
Refactoring: A series of small steps, each of which changes the program’s internal structure without changing its external behavior - Martin Fowler
Code left unchecked-in for a week is like milk unrefrigerated for a week. Eww. - James Shore
By far the dominant reason for not releasing sooner was a reluctance to trade the dream of success for the reality of feedback. - Kent Beck
Reading other people's code is the best way to learn. - Uncle Bob Martin
The mere presence of a great source control system doesn't obligate anyone to use it in a structured, rational way. No. That takes discipline - Jeff Atwood
Architecture without executable code is just an hallucination - Ivar Jacobson
Best code = non existent code - Amit Rathore @ Lean Kanban 2009

Note: where I can, I've credited or linked the source of the quote. Finding the source of a quote is like chasing a ghost. When a mentor says something witty, you might not know they are quoting someone else. If you are aware of a more appropriate source for any quote, PLEASE put a comment on the post and I'll do what I can to validate this. I mean no disrespect to anyone. I believe the risk of incorrect citings is outweighed by the value of sharing these wonderful nuggets.

Tuesday, August 25, 2009

Burndown charts as an indicator...

Jack Milunsky posted an interesting point in the Agile Project Managers group on LinkedIn. I normally agree with him and like his work (actually, I still do here)...

His core point is quite valid. The point of the burndown shouldn't be to drive a team towards focusing on the team's ability to match a perfect trend line. This is something I totally agree with. I've seen teams with perfectly straight lines on their burndown and I've learned that this is a big flag! That being said, his following sentence:
I believe that the underlying goal should not necessarily be about staying below the estimated time line in a burndown chart (although this would be nice).
..might set the wrong tone for a newbie to agile. I wanted to address that here.

Joe Blotner captures this well with the following statement:
Scrum doesn't solve your problems, just make them visible, so you can solve them.

...which I'm sure that Jack would agree with.

But... I want to state that I think the main goal of a burndown IS to trend downwards. This isn't the same as staying below the estimated line, but I want to be clear... if the trend isn't down, then you are going backwards. As a business person (PO), I would not accept a burndown going up or flat too long. This is a sign that I'm spending money and there's no sign of progress (both in uncovering all the unknowns and in making progress). I'd almost prefer seeing the line spike up and then start working back down so I know the problem is behind us. A flatline always triggers me to ask "but when will it end?"

That being said, if this is what was happening before agile, then Joe is correct. Agile has helped you focus on this and now you can try and fix it.

Little nuances I know... but I wouldn't want to see a new scrum team looking at their burndown and saying... "eh, that's okay for now... let's figure it out in a few days (or at the end of the sprint)."

Agile is not a metric, it's a journey...

As ridiculously fluffy as that sounds, it is true! You can't measure your team's agility and say, "Yup, we are there!". It is a mindset. All of the agile approaches (XP, Scrum, Lean, etc) are simply schools of thought.

Jai put up a very good post which triggered this discussion:
... Then he added that if you are not doing pair-programming or continuous integration, how can you say that you are agile. There I got the idea that what he was confused at.

Sometimes it is hard for people to differentiate and digest the differences between the Agile practices and many of the XP practices. They somehow get mislead by the idea that the XP practices etc are part of Agile. And Agile enforces these practices with it.
Many interesting comments are starting to come in, but mine was this:

I’ve dealt with this myself. I try to explain that the manifesto was the result of many people with different ideas on how to solve the same problem. The manifesto is the solution to the problem strategically. The “denominations” of agile are tactical approaches to solving the problem. Scrum is product and schedule focused, XP is engineering focused. And oh yeah, many of them have converged over the years.

Contrasting XP/Scrum with Kanban, Crystal, Lean, etc also tends to help. When people can see the common outcomes from the different approaches, it starts defining Agile by the results and not the chosen methods.

Follow the discussion further here.

Monday, August 24, 2009

Quote Series Part 4 - Metrics & Managers

This is part four of the series, to see what this series is about, click here.

Quotes on "Metrics"
Another purpose of measuring capacity is to improve throughput. If you plan for less than your capacity, you get less done than you could have. If you plan for more than your capacity, you get less done than you could have.

Having a plan with "enough" work in it less some slack to improve the probability of meeting commitments increases the amount of work that gets done compared to planning for too much or too little.
- Kent Beck
Once you start measuring something, you can easily end up in a situation where the measurement itself starts influencing the things you want to measure. - unknown
Quotes on "Managers"
Management owns the 4 T's (time, talent , treasury, target )... everything else is up to the team. If you have a issue that affects one of the T's, then ask management for input. - Tim Ottinger
Message to Management - eventually, you can push too much change at once.... back off and let the team normalize. - JB Rainsberger
In my experience, it is the leader’s (manager’s) job to intervene in the case of inappropriate behavior, and when he or she does, the rest of the team will be grateful for the intervention. It is being a “servant” to the whole team by suppressing the individual behavior that will keep the team from being successful.

It’s not about telling people what they are doing wrong. It’s about constantly steering everyone on the team in the direction of success, and never letting any individual compromise the progress of the team toward success.
- Mary Poppendieck

Note: where I can, I've credited or linked the source of the quote. Finding the source of a quote is like chasing a ghost. When a mentor says something witty, you might not know they are quoting someone else. If you are aware of a more appropriate source for any quote, PLEASE put a comment on the post and I'll do what I can to validate this. I mean no disrespect to anyone. I believe the risk of incorrect citings is outweighed by the value of sharing these wonderful nuggets.

Friday, August 21, 2009

Quote Series Part 3 - Stories

This is part three of the series, to see what this series is about, click here.

Quotes on "Stories"
Devalue the dollar - story points should be small, 1 pt - ObjectMentor coach
Stories add functionality, not technical layers. - ObjectMentor coach
If all stories are less than 5 days, we might not need a task breakdown. - ObjectMentor coach
All stories should be small enough to be delivered in less than a week. - ObjectMentor coach

Note: where I can, I've credited or linked the source of the quote. Finding the source of a quote is like chasing a ghost. When a mentor says something witty, you might not know they are quoting someone else. If you are aware of a more appropriate source for any quote, PLEASE put a comment on the post and I'll do what I can to validate this. I mean no disrespect to anyone. I believe the risk of incorrect citings is outweighed by the value of sharing these wonderful nuggets.

Thursday, August 20, 2009

A further experiment in ScrumBan…

I’ve recently evolved my company process to include WIP limits, but before I share this story, I must first provide the following background.

When I started at this company 2.5 years ago, there was a large divide. I was trained in PMI, was a CSM, and I was a staunch advocate of XP/Scrum by the book. On the other side of the divide, the company had little process, little documentation, no source control, and made minimal attempts to plan work a day or two in advance. One could say this was a recipe for disaster, but this is a startup… and the point of hiring me was to improve as they doubled the size of the company.

Several things have happened since then:
  • retrospectives and weekly iterations were quickly adopted
  • source control is now in place
  • we put tools in place to manage our work (VersionOne)
  • standups have become common for both teams and projects
  • we’ve modified the 3 questions
  • we now use a ScrumBan inspired board
  • most importantly, I’ve learned that there is more to Agile than Scrum/XP… I’ve become an interested follower/borrower of Lean and Kanban practices. This is an important step for me as a coach since not all environments fit the Scrum/XP model. A mixed bag of tricks helps win the debate, especially when it is gamed against you!
So, what is the new problem of the day? I’ll call it the plan-to-budget problem. I’ve struggled for 2.5 years to find a way to get the company to plan work based on the available capacity. We’ve always had “BUT-we-need-to-do-ALL-of-it”-itis.

I’ve explained velocity and scrum, but this was viewed as too expensive to pursue. “Why should we estimate everything when we only care about certain parts of it meeting a specific deadline?” This is a good point. If only a small portion of our work is deadline driven, and the rest is “do as you can in this order”… then putting time into estimating and projecting everything might lead to waste. (Although this is contradictory to “I-want-all-of-it-by-next-month”-itis.)

Thus, I reduced focus and tried a top5 concept. Hey CEO, pick only 5 things that are important for this week, we’ll do our best with that set before touching other stuff. This worked well for a while since it forced us to admit we can’t get everything done and focused on fewer items. It reduced our “in flight” work… for a while. Two things derailed this approach.
  1. The CEO found ways to assign work to people outside the top5 set (most people can’t say no to the CEO/founder when approached).
  2. Not all items were the same size (scream together now: ESTIMATE!) so 1 large top5 item could clog the whole pipe.
We let go of this concept and evolved our breakdown further. I was happy to push for smaller stories and quicker closure. Appropriate sizing is a great stress reducer for the team, especially when you involve them in that process. But we slowly returned to our problem of demanding more work than we have capacity for.

This is where I started thinking about Kanban’s WIP limits. After all, this would fit our model well, and we already have the board in place. Unfortunately I knew that this would be bypassed just like the top5 limit. Our problem was a cultural problem, and I had to tackle it at the source.

So, we’ve started a new trial change in our process. After 3 hours of debate, I was able to convince management of the following (meaning they agree with these):
  • Giving one person too many things at once will slow down throughput
  • Swarming is a good way to get things done faster
  • Saying we have to do everything doesn’t mean it will get done
  • Not deciding on priority means it will get decided by the people doing the work
  • Our biggest issue might be over-committing (actually, over-requesting since nobody was necessarily committing)
The solution? Headshots! I made little headshots of each team member. We plan the queue of work and then prioritize it. Then the CEO points at a card on the board and says “I want that first”. We put 1-N heads on it based on availability, capability, and size of work. The CEO keeps pointing at items until we run out of headshots. If he points at big things, he picks less stuff; if he points to small things, he can pick more (Budgeting to capacity!) When a person frees up, they move to something else on the board. Everyone on the team might have a few things assigned to them in VersionOne, but they KNOW which item is most important (the one with their head on it on the board). Everyone on the team focuses on helping each other finish these items before starting new things. All of this is clearly transparent on the board! It's not rigid like scrum velocity or Kanban column limits, but it is a place to start and a way to prove value (a door to further improvement).

Summary: We aren’t doing true scrum, but some of the pieces. We aren’t doing true Kanban or Lean, but some of the pieces. We aren’t truly self-empowered, self-managed… but somewhat. I would be the first to declare we aren’t “agile” as defined by most in the community. BUT, I’m getting to the point where I believe we have a system that works for us (2.5 years ago, we were a demand-and-control company led by the CEO). It’s a hybrid of many agile approaches, driven by my teaching of agile philosophies, allowing this company of ~70 work better together. Hopefully this new change will help us overcome our capacity/planning issues, only time will tell.

Wednesday, August 19, 2009

Agile FAIL!

Sometimes I feel like a fireman... I read things that just don't make sense and I want to pour water on it and put the fire out. I have slowly come to realize that there are more voices proclaiming stupid things about agile than I can counter.

Let me share with you what bothered me today...
Agilists seem intent on advocating their rather extreme view of agile including no documentation, little planning or architectural design and less control. The mantra is ‘give the software developers free reign and you will get better software’.
Yeah... this is a FAIL! (on the part of the "Agilists")
Most IT projects exist to enhance the capability of the organization.
I'm not completely sure what "IT project" means in this context... but they don't exist for the organization. All projects are about business value and enabling profit.

Partial Fail?
...at the very least a minimum of documentation to prove the IT team and its immediate customers understand their scope of work and other constraints and know how they will achieve the outcomes needed...
Documentation is needed in a minimal sense... but whatever happened to working, accepted, purchased software as the best measurement?

Partial Fail!
The agile extremists may do well to consider [self discipline] and focus on meeting the needs and expectations of all of the stakeholders involved in their work.
Very good point. Whoever this person got their impression of agile from.... VERY BIG FAIL!

Quote Series Part 2 - Estimates and DONE

This is part two of the series, to see what this series is about, review part 1.

Quotes on "DONE"
One of the goals of the sprint is to measure what you have done - ObjectMentor coach
Burn-up should happen every day to stop scrunch stress (all things shouldn't finish on the last day) - ObjectMentor coach
If we’re not shipping our software when it’s ready, it’s poor business practice. If we’re not sure whether our software is ready, it’s poor software practice. - Ron Jeffries
Make Ship Happen - Todd Little
Quotes on "Estimates"
Ability to estimate correctly is not an ‘ability’ … it is a fluke and lucky guess - Roy Morien
Estimates only help us take action to get to the next step - unknown

Note: where I can, I've credited or linked the source of the quote. Finding the source of a quote is like chasing a ghost. When a mentor says something witty, you might not know they are quoting someone else. If you are aware of a more appropriate source for any quote, PLEASE put a comment on the post and I'll do what I can to validate this. I mean no disrespect to anyone. I believe the risk of incorrect citings is outweighed by the value of sharing these wonderful nuggets.

Monday, August 17, 2009

Quote Series Part 1 - Agile

Over the years, I've collected quotes from my agile surroundings. This collection has been growing for almost 5 years now. I've used it to inspire my teams by writing a new quote on the top of the team's wipeboard every few days. It keeps them thinking and on their toes. I've decided to do a series of blog posts to share them with all of you. (it's also good filler while I'm on leave due to the birth of my 2nd child and many in the industry are at Agile 2009.)

Quotes on "Agile"
My definition [of agile] is that you accept input from reality, and you respond to it - Kent Beck
An agile manager must: manage & deal w/ risk, be results oriented, have high energy, be a team player, have multi-tasking ability, be improvement oriented, listen first and speak second - Lee Henson
Agile is:
- A project management process that encourages frequent inspection and adaptation
- A leadership philosophy that encourages team work, self-organization and accountability
- A set of engineering best practices that allow for rapid delivery of high-quality software
- A business approach that aligns development with customer needs and company goals

- Mike Cottmeyer / Jon Strickler
Deliver Frequent Releases, Empower Teamwork, Inspect and Adapt, Build Quality In - Karl Scotland
Agile != following steps, Agile != tools training
Agile = individuals & interactions, Agile = Collaboration & Teamwork
Agile = Environment Matters!
Agile = learning from experience
Agile=reflection, Agile is an adjective not a noun!

- Rachel Davies (Agile 2007)
Agility might be said to be about encountering all the problems so early and so often that the effort to fix them is less than the pain of enduring them. - Ron Jeffries

Note: where I can, I've credited or linked the source of the quote. Finding the source of a quote is like chasing a ghost. When a mentor says something witty, you might not know they are quoting someone else. If you are aware of a more appropriate source for any quote, PLEASE put a comment on the post and I'll do what I can to validate this. I mean no disrespect to anyone. I believe the risk of incorrect citings is outweighed by the value of sharing these wonderful nuggets.

Wednesday, August 12, 2009

The PO is part of the team, get over it!

The other day I posted about charging a fine for being late to the standup. I knew this would get some reactions, but one thing I should have been clearer about was that this wasn't a team problem, it was a PO problem. Sure enough, several of the LinkedIn forums got fired up over it and some heavy hitters had some good points to make (thanks Rachel Davies!).

I agree that this concept can backfire (fine, I'll pay the fine so I don't have to come), and there are solutions to that (double the fine for each offense). I also agree that if the majority of people need a fine to appear at the standup, then there is a much bigger problem occurring.

So, that background aside... one of the conversations appropriately focused on the issues we were having with the Product Owner. Why didn't he want to participate? Why was this an issue?

Lesson learned on that point: when this company went agile, we trained the developers, then the QA and analysts. Following the rules of Scrum & XP, we understood the metaphor of the Chicken and Pig very well. Unfortunately by following this rule, we optimized the team but de-optimized the whole value stream. It wasn't until the PO's got some agile training that they understood how to evolve for the new agile world.

This post is in response to the following comment in regards to fining the PO for being late to the standup:
Why wait for the PO for a stand up? The PO should not be in a position to cause the problem. We try and utilize the Chicken and the Pig approach.
And my response:
There are many people who feel the PO is a member of the team: http://www.danube.com/blog/dan_rawsthorne/who_is_the_project_manager_in_scrum
Thus making them a Pig.

Also, the chicken and pig concept is dead in my mind. It's a coping mechanism for bad managers:
http://www.langrsoft.com/blog/2008/08/pigs-chickens-and-asses.html

As our agile team matured, we found that many of our early retrospective discussions led back to the fact that the PO wasn't accessible enough. When your PO is the voice of many customers distributed globally, the PO is very important. If you have direct access to your customers (example: internal employees), then this might not be as important.
The last thing you need is for a team to go to the sprint review and demo lots of software that fails PO acceptance. Instead of making decisions in his absence and hoping they were right, avoid this waste and just treat him as a team member. If you can't do this, then get a proxy in place (lead analyst), or get direct access to the most important users to reduce the risk (beta customer).

Monday, August 10, 2009

Managers are not Super-You's...

Nancy McCall wrote an interesting post about somebody's thought that Your boss should do your job better than you.

Her points were:
- Managing people requires different set of skills than developing software, or whatever the job is of the group being managed.
- Proficiency in any area is worthy of respect, regardless of whether is it your area.
- It is not all about you.
She goes into further detail, feel free to read the full post.

I commented further:

Agree. I’ve modeled my management career path after those managers that were best at enabling their team to do something great with their collective powers. This typically meant that the team was collectively much smarter than the manager, but it was the manager that helped them get there.

If I had to be a better coder than the people I help manage, I’d be out of work. Instead, I’m a valued person in my organization because I can do things they can’t… and they come much more naturally for me than for them.

Friday, August 7, 2009

Say what you'll do, do what you say...

I've been noticing something new lately. I schedule a meeting and everyone confirms it, then about 30 minutes before the meeting several people come up to me in person or by phone to confirm that we are still having the meeting.

What?

Am I that distrustful or unpredictable? Is there a history of you showing up for meetings and them not occurring?

I'm confused by this... but then I got to thinking about it more. I realized that I've had friends or family do it also with gatherings. This behavior has risen in the last few years. What I don't know is if it has anything to do with our constant micro-distractions with technology, or a decrease in respect for each other.

Don't get me wrong, it bother me that people waste my time to verify that I won't be wasting theirs... but what I'm really concerned about here is that people do this to protect themselves against something that must happen to them all the time. This something is hugely disrespectful. It's the act of not following through.

I was raised in a community and culture where you stated what you were going to do, then you did it. If for some reason you couldn't, you had better set expectations in advance as soon as you could. If you didn't, you paid the price by harming that relationship. You didn't deserve to receive mutual agreements from that person in the future after that mistake.

Agile is about this. Standups inspire this. Reviews demand this. Planning and Velocity requires it. WIP limits assume it (I've seen managers bypassing WIP on the sly!). Retrospectives if run properly will inspire it also. Without it, everything starts to fall apart.

So people: say what you'll do, and do what you say. Follow through. Get to DONE! And don't limit this to your work, but include it in your relationships with other people.

Think about how much time we can save not second guessing stuff anymore!

Wednesday, August 5, 2009

Late to the standup, pay a fee! (or not?)

In my last company we realized something very quickly. If the standup meeting is only 15 minutes long, then anyone who is 5 minutes late probably causes the meeting to extend by 30% while we repeat stuff. If we aren't repeating stuff for the late person, then you have to question how engaged that person is in the team.

With that in mind, we started complaining about lateness over 1 or 2 individuals... one of which was the PO. His initial solution was to start without him. We poked at this and it became "meet without me". This turned into our marginalization of his input, which degraded to major problems during sprint review because the customer (PO) wasn't on the same page as the team.

So, we agreed to make this marriage work and the PO said he'd make an effort.

The cycle started over. He always had excuses. This meant that other people started riding his coat-tails and coming late too. Eventually the standup was a mess because it wasn't predictable. People who were on time got punished by those who were late (and didn't respect the team).

How did we solve it? We added a fine. Now, Foo wrote a great blog post about how this will backfire. Once you put a price on something, it's valued a different way. Sure enough, our PO threw $50 in the goldfish bowl and stated "That will cover me for the month and buy pizza for the team" as if he was doing something good.

New rule... $1 / day for being late, fee doubles for consecutive days.
Outcome: PO is present every other day and buys pizza for the team every month or so. This was a compromise everyone could live with.

Tuesday, August 4, 2009

Before agile came along, life was easier for me...

The problem with Agile is that it helps us realize early that there might be problems. Granted, this gives us time to solve the problems and get the project on track, and it allows us to have a higher success rate.

But I miss the good old days where we happily worked for months until the death march started. It allowed us to stay blissfully happy and then blame management for the last 3 weeks when things went wrong. Some of us would get good at finding long projects where we could work for months on lines of code and then bail on the work and jump to another job or company right before it went into the crapper. Becoming an expert in our skillset was simply about perfecting our selection of projects and timing them well.

Now we actually have to be on top of our game every day! That's a little bit more challenging than I expected. I went and got this computer science degree so that I could sit in a cube and write code and get paid lots of money for it. What's going on here?

Yeah... unless this is the first time you've read my blog, you know how I truly feel!

Read the Cutter Consortium's version of this viewpoint.

Monday, August 3, 2009

Agile Documentation, what is it?

Elroy Serrao asked a question leading to a good discussion about documentation on LinkedIn's Agile Alliance group.

His statement:
The whole "document via index cards" idea felt a bit weird though. Partly because I haven't been able to really view physical "index cards" as something that can be tracked, searched etc over a long period of time. So I was wondering if anyone would be willing to share their experiences, best practices etc. in this area.
The following is a couple of the high notes:

From Siddharta Govindaraj:
Think about how much value a piece of documentation produces. If you think it is worth it, then go ahead. If you feel it is overhead then dump it.
You need to ask yourself three questions: Who is the documentation for? What is it for? How will it be used?

From Levent Gurses:
There is no way in the world that I, or anyone else on my team, will spend time digging a cabinet of index cards to find out about the details of a story that happened 3-4 months ago. It will just not happen.

Instead we use a modern WIKI, like Confluence - which among other things keeps page versions. Requirements and stories captured in Confluence are always current and traceable. Combined with SCM labels and release notes, any person on the team is always 100% sure what's in Production, what's in Testing and what's currently being developed.
From Kevin Schlabach (me):
I'm most aligned with Levent's answer, but here's my simplistic cut at it-

If you do TDD... add a database & architecture model to your tests and you have your tech documentation (as much as is worth keeping up to date).

If you use automated Acceptance Tests... add a domain model and you have your business documentation.

If you use an electronic system for backlog management... you have your project documentation.

If you pair program and rotate pairs daily, you insure knowledge is spread throughout the team.

If you layer on a wiki, you can capture conversations for the few days it's needed until working software is built.

If you don't do some of these things, you might require more documentation to cover you when you want to ramp up new people or explain your API's to other groups.

This is a simplistic overview, but what I'm getting at is that you still need some documentation that goes beyond your index cards, but it can be a living, breathing part of your process.

Read up on some of Alistair Cockburn's work (Crystal). By applying game theory, you always think about working today to insure success (wins) tomorrow. Documentation is meant to be a way to survive in the future when needed.
From Gary Tinnes:
I have a rule: “the amount of a document that is read is inversely proportional to its size”. If you document, keep it short with lots of white space to make it look smaller than it really is. Focus on bullet points (clarification if needed) and graphics.