I’ve been talking Agile at the Embedded Systems Conference. Last week was my 7th year of participation. A few common questions usually come up. I’ll paraphrase the questions and answers.

Documentation
“We had a team doing agile. To them that included not doing any documentation. We need documentation once we go into maintenance. Is doing documentation allowed in Agile?”

That question I answer like this.

“Every team’s needs are different. If you have a need for documentation you should build it. But you should not build it without good reason. I like to challenge my clients to identify their documentation needs. One of my clients told me that its needed because the process manual says so, and the process people will be after us if we don’t do it.”

So, I ask the audience member “What purpose does the document serve? If we know its purpose we can find the least expensive way to create it.”

“We need the documentation to support a hand-off to maintenance.”

“If you want a document for maintenance, the cheapest time to build it is right before the product is handed-off. You can write the whole document based on the existing design, rather than the anticipated design. The anticipated design would be wrong at least in part and likely incomplete. But once the design is proven you will know what important information should be included.”

Then he replied “If we do that we won’t do the document. Its been proven time and again. At the end of the project the engineers are immediately pulled off to work on the next hot project.”

This is deja vu all over again. “Let’s consider some alternatives. If you do the document at the beginning, you are basically guessing. Your guesses may be well educated, but still they are guesses.” I continue “I expect that it is more expensive to write the design document based on guessing and to continually update it through the process than to write it based on what was actually built?”

People usually see the logic in this, but still do not trust themselves so I add “A decent compromise is the do the high-level document incrementally. Each iteration, any architecturally significant ideas are documented. Be careful to keep the design at a high-level to avoid the churn at the detail level. Details will change and you’d rather not have a lot of rework. Save the details for the automated tests.”

I’ve seen this approach work well. But be warned, there is not only one solution. You must know why you are producing the documents, and consider the value and cost of the documents. A co-located team can live with a lot less documentation than a distributed team.

Agile developers prefer to have detailed documentation in the form of executable tests:

• Unit tests – detailing code usage.
• Component test – detailing how a component behaves.
• Acceptance tests – detailing that a module meets is requirements.

Rework Concern due to Story Implementation Order
“When the features are broken into little pieces and ordered by the customer, what if something near the end of the release causes major rework?”

I respond “This is a risk, but is usually not a problem if your code is well refactored. But hypothetically let’s say you have a release backlog of one hundred stories. One of the stories requires Chinese output. Your customer does not need the feature until right before shipping the product to Hangzhou, so she schedules it late in the release plan. The engineering team sees this a considerable technical risk. When there is a high risk story placed late in the development cycle, give the story a high estimate. This makes the risk more visible to the customer. You can then suggest breaking
a piece of the story off and moving it earlier in the release to mitigate the bulk of the risk.””

Rework Concern when there is little up-front Design
“I’m concerned about the lack of up-front design. What if some story causes a lot of rework to the current design?”

“Would you agree that you have this problem when you do an up-front design? You can’t think of everything” I ask.

“Yes, that’s true” my questioner replies.

“How many of you have 10-15 year old code bases?” I ask the audience. A bunch of the hands go up. “Who is working on brand new code?” Very few hands go up.

“That is interesting, you are all working in existing code bases. I suspect you have this issue all the time. Some of this year’s requirements were never dreamed of 10 years, 5 year, or even a single year ago. Probably many of your code bases are overly complex, hard to understand, and hard to modify right now. I think Agile teams have a big advantage. We have practices for evolving code. TDD and refactoring are designed to support the evolution of a code base. So the bottom line is, you will be better able to handle architectural changes if you have refactored code with good automated test coverage.”

Pair Programming
“What if you don’t do pair programming?”

“Pair programming is not practical at times, or might not fit a group’s culture, or physical office layout. When monitors are in the corner of your cubes, pair programming is a pain. Its best to have a team space where people can pair, but anyway… If you are not going to pair it is important to consider its purpose, so we can make up for not doing it. In essence pair programming is a real time code review and more. It spreads knowledge and helps improve quality. Without pair programming you need to look for ways to spread the knowledge and keep the quality high. Two options are daily code reviews, or swapping code between developers one day to the next. Code swapping may sound crazy, but with automated unit tests in place, and an agreed to and followed coding standard, code can be swapped readily among knowledgeable team members. Don’t think there is only one way, find a way that works for your team the fosters communication, supports your coding style and helps to improve quality.”

Then a follow on comment “I’m concerned about being paired with the same person for weeks at a time.”

“Pairing is short term, maybe a few hours or a day max. Partner switching sounds disruptive, but much to my surprise I have found that it is not. Switching helps to spread the knowledge and avoids pair fatigue.”

“What if your partner has a hygiene issue?”

“Keep mints on hand and give him a Bath and Body Works gift certificate.” (Just kidding, no one asked that, but someone wanted to.)