Project documentation

I got the following questions from a friend who wants to understand agile practices prior to implementing them on his project. I will try to answer them based on my experience.

” What needs to be documented in agile ?”

The Agile principle is “Working software over comprehensive documentation”. Documentation can be an intermediate product towards delivering this working software. It can be created for reference or for articulating business rules and in case of distributed development, to communicate ideas.

Chris Matts puts this well – The real aim is to build the knowledge in the minds of the developers and business users rather than focus on creating a document that may well not be used.

Having said that, there are real requirements to produce documentation as an end product such as for legal compliance or for product patents. Sometimes documentation is required for future support activities, but there are other better ways to handle these requirements.

“How do stories get documented ?”

At Thoughtworks, we have developed a practice to determine project /programme requirements in facilitated workshop sessions. Stories are captured during those sessions, typically by the clients themselves, using the following format.

As a .. <user who requires this feature>
I would like .. <goal>
So that… < business justification

The stories captured in this fashion supported by process flows and scenarios are sufficient for estimating and prioritising and thus, for further planning.

During the development phase, the stories prioritised for development are further corroborated with acceptance criteria, a set of conditions that the story must fulfill to be considered complete.My colleague Dan has an excellent article describing the intent and the anatomy of a story in detail.

“Are the story documents kept after its been implemented ?”

XP practitioners derive a catharatic experience from tearing story cards after they have been implemented.

In practice, the story documents are largely captured electronically either on the WIKI or in Word/ Excel documents or as automated acceptance tests – so does not make sense destroying them. The supporting documents that you build around documenting your business rules, UI design or implementation logic are useful even beyond the implementation.

We have used FIT tests as living documentation which live beyond the development phase. During development, they are useful for specifying acceptance criteria in a testable form and beyond that, they are useful as a regression test suite.

“How are the stories organized ?”

I like organizing my stories on the WIKI as that gives you multiple advantages. WIKIs allow you to have a view which lists the entire scope of development by listing the stories, their status, their priorities etc. You can have individual page/placeholder for each story which you can flesh out as they get prioritised for development.You can have another view where you can reference the stories by iteration. Multiple views are useful for all the stakeholders in your project including your client, project manager and the development team.

We have also used Trac , JIRA and Sourceforge for organizing the stories. Based on Thoughtworks’ collective experience in project management, our product division would shortly be launching an integrated project management tool called Mingle , which I expect to start using on our projects.

“How are they kept for future references ?”

As for maintaining documents for future reference, it is better for the existing development team to summarize the whole project as it has been implemented in a seperate document. Future reference requirements usually stem from the need to support or enhance the existing application. So important decisions taken during the project such as key architectural decisions, business rules, workarounds and UI flows can be very useful context to a new person on the project.

Support artifacts also need to be created in the context of the audience and the intent. For example, a working prototype of the application was extremely useful as a training tool for the internal staff instead of a wordy user manual in a previous project I worked on.

“If a feature is changed in the future is the same story accessed again and modified?”

The simple answer is no. You should create a new story for the same. You could mark the original story to say it has been superseded by a new story. Stories are also planning units and there are implications on project velocity* calculations and scope management that need to be considered here.

If your documentation is a living documentation like FIT tests, you will need to change the original documentation for it to stay relevant.

I would be interested in getting more perspectives on the above questions myself. So if you have wisdom to share, drop some comments here.

* – Project Velocity is the throughput of the team in a fixed period of time measurable in a unit of business delivery (Thanks Dan)


What is the business case for a disruptive business model / technology ?

Imagine being commissioned by Chad Hurley to work on a project for “Online video sharing” or by Steve Jobs to work on a project to deliver “Digital Music Player with a cool interface”. What business case or strategy would they have shared ? There was no existing market for their inventions before they introduced it. They could share with us their vision as shaped by the trends , the changing customer behaviour and the enabling technologies , but they would have been hard to pin down on what they thought the business benefits case might look like. In fact, Youtube did not even have a revenue model till a year after its launch

What does this mean for the well-intentioned analyst who believe their job is to protect the customer’s stakeholder value by coaching them against investing in such projects ?

The truth is that it is not always possible to judge disruptive technologies or business models using traditional tools of analysis. In fact, Clayton Christensen, the Harvard Professor who coined the term “disruptive innovation” advises us of the following

“In highly uncertain situations that typify disruptive innovations, following the typical strategy-making process just doesn’t work. In these uncertain situations, some companies believe they need to fly by the seat of their pants. However, companies can follow a rigorous process by using an emergent strategy supported by a discovery-driven planning process that enables them to adjust their strategy when they encounter unanticipated opportunities, problems and successes.”

As a business analyst the role is more about supporting this emergent strategy development process and not just a resource allocation filter. Admittedly this requires a significant mind-shift. Michael Hugos gives us a very important mantra – Be strategically focussed and tactically agile to meet the needs of a customer in an dynamic business environment. Delivering business value is as much about offering flexibility for the business to change direction as it is about delivering incremental revenues or saving costs.

How to hit the ground running

I was watching “Ali” the other day with my dad. While I thoroughly enjoyed the movie, I realised that my dad was struggling to make sense of what was going on.. I realised that the movie assumed that the viewer was already aware of the 60s movement in the US to gain racial equality, Malcolm X and the politics of Nation of Islam, the Vietnam war etc. Years of watching American television, movies , documentaries and a lot of reading allowed me to get the necessary context, which my dad lacked.

Too often, consultants face the problem when they land at a new client – there are huge unknowns such as the client’s existing business process, existing systems and the business environment. At this point a good amount of jargon gets thrown about by the user base without necessarily setting the context. Some of this jargon can also be wrong such as false domain terms, using system names interchangeably with business processes, poor domain design etc. Its possible that there isnt a safe zone for the consultants to ask the dumb questions. Its difficult for the consultants to hit the ground running when faced with such barriers to information.

Kathy Sierra draws a distinction between “Jargon” and “Buzzword” in her post , the former being the lingua franca of experts and the latter being used to impress/ mislead others. In our example, the users /customers have built their own jargon over the years based on their specific work environment. The consultants, on other hand, may possess certain knowledge about domain, but is most probably not conversant with the jargon used. Without resorting to buzzwords which can be counterproductive, the consultant needs to find a way around the jargon used.

Here’s what I have done in similar situations like this earlier

  1. Read ! Read existing documents , WIKI pages, public websites, etc. Some clients also have internal induction training courses – get your hands on those, if possible.
  2. Model your understanding of the system and illustrate it visually. The users may break the model through different scenarios, which is actually a positive thing. (For more details, see Chris Matts’ article on Negative Feedback)
  3. Apprenticeship. If possible, get to be an apprentice to a customer and help them in their work. Suddenly “Damn ! We have got too many NIGOs today” starts making a bit more sense. (NIGO = Not in Good Order). There is another side benefit here – we may actually begin to have empathy for their daily jobs.
  4. Related to apprenticeship, one can volunteer to test existing systems for a short period of time. This usually provides a good context of how users actually use the system.
  5. Maintain a “Jargon” or “Glossary” page on a shared WIKI or something similar. Most users are happy to answer direct questions such as ” How is a CFD different from Swap” ? or ” Where does GLADIS fit in the whole trade cycle” ? This is of course, assuming, that you know what a SWAP is and what a trade cycle is.
  6. Get the user in a teaching mode e.g. Lets say we are building a new financial trading system. In our analysis sessions, we should ask the user to think of a situation where they have just set up an entirely new fund. The user is asked to think about a single product which they wish to trade, consciously keeping out any complexities. Once the simplest scenario is achieved, start layering it with other complexities and dimensions. The happy side effect is that you would also end up with the right set of stories to work with.
  7. Build relationships at client site at all levels. Juniormost people are sometimes also the best sources of information as they have recently been through a learning curve themselves.
  8. Finally, document your learning. It is quite possible that you may have to handover to another person and you dont want them to go through the same pains again.

Let me know how these tips work for you. Or you could just be like my dad who says “Theres no such thing as a dumb question – there are only dumb answers”.

Analysts should think like entrepreneurs

Every business has a simple model to begin with. An entrepreneur, while setting up a new business, would normally follow the steps listed below

  1. Assess the need for the service/product
  2. Determine whether it needs to be greenfield development or can be purchased outright
  3. Start with the lowest initial outlay possible for the business
  4. Gather customer feedback
  5. Identify improvements to service/products
  6. Implement and test the improvement
  7. Go back to step 4

An Agile analyst should think like an entrepreneur for the system that they are building. The same set of steps apply again

  1. Assess the need for service/product
  2. Determine whether the product/service can be bought or built
  3. Start with the simplest model of the system
  4. Showcase
  5. Identify incremental requirements
  6. Implement and test the requirements
  7. Go back to step 4

Will the real customer please stand up?

One of the prime requirements for the success of Agile Projects is to have an “onsite customer“. In reality the real customers rarely have either the time and often, the inclination to be involved with the development team on a full time basis. After all, there is a business that needs to be attended – things dont come to a standstill while the system is being developed. The accepted wisdom is to have business analysts serve as “proxy customers“, thereby leveraging the real customers’ time. Business analysts are presumed to have the necessary skills and experience to drive out the project requirements by having sessions with the real customer and therefore, be in the position to make the best decision for the project. So far so good.

Unfortunately,there is an additional layer that gets introduced within the fray.The real customer is often hands off, and a token customer is assigned to liaise with the business analyst. This is typically a junior member within the user community or a business analyst / domain expert working for the client.This person might have the knowledge of the functional area for the system, however they usually do not have the same level of authority and big picture outlook that the real customer does.

The risk of not having an onsite customer has now been replaced with a different type of risk – Risk of having a token customer. Listed below are some of its possible implications

1. The token customer’s future career / bonus is usually contingent on the mandated success of this project. Conventional wisdom about a successful project is the delivery of agreed functionality on time, on schedule and to the agreed resources. Usually such mandates are taken too literally and as a result, any form of negotiation is viewed as compromise.
2. Productivity of the team is assumed at the beginning of the project and subsequently, calibrated over a period of time during the iterations depending on the team’s performance. This may mean changes required either in scope, time or resources and usually, our token customer is not the best equipped to make the decision.
3. The token customer may have previous experience with developing a similar system and this could result in typical analysis anti-patterns such as “Re-inventing the wheel”,”Re-inventing the square wheel”, “Golden Hammer” etc. Scope creeps can occur as the token customer may try to shoehorn some requirements within the existing story list.
4. Difficult to establish the business case for the system as the token customer may not necessarily have the complete knowledge of the drivers.

Here are some of the mitigation strategies that have been tried before
1. Involve the real customer as much as possible, especially where key decisions need to be made. Showcases, iteration planning meetings, kickoffs etc. are ideal candidates for the customer involvement. Ensure that the meetings are short and therefore, would not tax the schedule of the customer heavily.
2.The success criteria for the project should get defined jointly between the team and the customer. This ensures that the mandate given to the token customer is aligned to the development team’s delivery commitment.
3. Educate the token customer on their roles and responsibilities within an Agile project. Give examples of different scenarios that occur within an agile project and the different decision points. Ensure that the escalation points are identified as well.
4. Manage the scope at story level tightly. By documenting all key assumptions made during the story identification, estimation and detailing, the BA will have the right arguments to make when negotiating with our token customer.
5. Structure the engagement to have a senior member of the development team emerge as a trusted advisor to the client.This senior member should be able to coach the real customers/ sponsors to identify the business value within the requirements.