Tag Archives: extreme programming

The Agile Manifesto – Essay 3: Working Software over Comprehensive Documentation

Learn more about transforming people, process and culture with the Real Agility Program

How much documentation does it take to run a project with ten people working for six months?  For some organizations it takes way too much:

Photo of heavy documentation for software project

This binder (about 3 or 4 inches thick) is all the documentation associated with such a project.  In looking carefully at the project, creating the documentation took far more time than the time spent on designing, writing and testing the software.  Yet, the documentation does not produce any value.  Only the software produces value.  The Agile Manifesto, asks us to focus on the outcome (working software) and to make tradeoffs to minimize the means (comprehensive documentation).

The Agile Manifesto asks us to challenge our assumptions about documentation.  In many work environments, documentation is an attempt to address some interesting and important needs:

  • Knowledge sharing among stakeholders and the people working on a project.
  • Knowledge sharing across time as people come in and out of a project.
  • Verification and traceability for contracts or other compliance needs.
  • Decision-making and analysis for business and technical problems.
  • Management oversight and control.
  • Various aspects of individual accountability.

Documentation is usually heavier (more comprehensive) the more the following circumstances exist in an organization:

  • Geographical distribution of people.
  • Lack of trust between people, departments or organizations.
  • Regulated work environments.
  • Depth of management hierarchy.
  • Number of people directly and indirectly involved.
  • Knowledge and skill sets highly segregated between people.
  • Culture of respect for written texts.

Working Software

What if the software itself could address the needs that often documentation is used to address?  Let’s look at them in turn:

  • Knowledge sharing among stakeholders and the people working on a project.
    If the software is functional at all stages, as supported by Agile methods such as Scrum and Extreme Programming, then the software becomes an effective representation of the knowledge of all the people who have participated in building it.
  • Knowledge sharing across time as people come in and out of a project.
    Software that is technically excellent is often easier to understand for people who are new to it.  For example, excellence in user experience and design means new users can get up to speed on software faster.  Use of good design patterns and automated testing allows new developers to understand existing software easily.
  • Verification and traceability for contracts or other compliance needs.
    Test-driven development (code) and specification by example (scripting and code) are forms of traceable, executable documentation that easily stay in-sync with the underlying software system.
  • Decision-making and analysis for business and technical problems.
    In particular, diagrams can help a great deal here.  However, electronic tools for creating such diagrams can be slow and awkward.  Consider the practice of Agile Modelling (basically using a whiteboard and taking photos) as a good alternative to precise technical diagramming if you are doing problem-solving.
  • Management oversight and control.
    Reports and metrics drive much of the traditional documentation in an organization.  Simplifying reports and metrics often leads to a clearer picture of what is going on, reduces the opportunities to “game” the system, and always results in lower levels of documentation.  As well, some reports and metrics can be generated 100% through automated means.  All that said, the fundamental premise in the Agile manifesto is that management should base decisions on what is actually built – the “Working software” by looking at it and using it.
  • Various aspects of individual accountability.
    If you really need this, a good version control system can give you the information for this.  Sign-offs and other types of accountability documentation are typically just waste that doesn’t actually help in process improvement.  Most people who are in high-compliance environments already have licenses and/or security clearances that provide this accountability.  If you software is working, however, then this isn’t even a concern as trust is built and bureaucracy can be reduced.

In my recent training programs as research for this article, I have surveyed over 100 people on one aspect of documentation – code documentation.  Every individual surveyed is either currently coding or has a coding background, and every single person had the same answer to a simple scenario question:

Imagine that you have just joined a new organization and you are about to start working as a software developer.  One of the existing team members comes up to you and introduces himself.  He has with him a piece of paper with a complicated-looking diagram and a full binder that looks to be holding about 250 pages.  He asks you, “you need to get up to speed quickly on our existing system – we’re starting you coding tomorrow – would you prefer to go over the architecture diagram with me or would you prefer to review the detailed specifications and design documents.” He indicates the one-page diagram and the binder respectively.  Which would you prefer?

(I’ve put up a Survey Monkey one-question survey: Code Documentation Preference to extend the reach of this question.  It should take you all of 60 seconds to do it.  I’ll post results when I write the next Agile Manifesto essay in a month or two.)

The fact that everyone answers the same way is interesting.  What is even more interesting to me is that if you think through this scenario, it is actually almost the worst-case scenario where you might want documentation for your developers.  That means that in “better” cases where documentation for developers may not be as urgent or necessary, then the approach of just going to talk with someone is a lot better.

Documentation and Maps

The problem with documentation is the same problem we have with maps: “the map is not the territory” (quote from the wisdom of my father, Garry Berteig).  We sometimes forget this simple idea.  When we look at, say, Google Maps, we always have in the back of our consciousness that the map is just a guide and it is not a guarantee.  We know that if we arrive at a place, we will see the richness of the real world, not the simplified lines and colours of a map.  We don’t consider maps as legally binding contracts (usually).  We use maps to orient ourselves… as we look around at our reality.  We can share directions using maps, but we don’t share purpose or problems with maps.  And finally, maps assume that physical reality is changing relatively slowly (even Google Maps).

Many times when we create documentation in organizations, however, we get confused about the map versus the territory.

Agility and Documentation

Of course, code is a funny thing: all code is documentation too.  The code is not the behaviour.  But in software, code (e.g. Java, ASM, Scheme, Prolog, Python, etc.) is as close as possible to the perfect map.  Software is (mostly) deterministic.  Software (mostly) doesn’t change itself.  Software (mostly) runs in a state absent from in-place human changes to that software.  Software (mostly) runs on a system (virtual or physical) that has stable characteristics.  The code we write is a map.  From this perspective, documentation becomes even less important if we have people that already understand the language(s)/platform(s) deeply.

This essay is a continuation of my series on the Agile Manifesto.  The previous two essays are “Value and Values” and “Individuals and Interactions over Processes and Tools“.


Please share!

Summary of User Stories: The Three “C”s and INVEST

Learn more about transforming people, process and culture with the Real Agility Program

User Stories

Learning Objectives

Becoming familiar with the “User Story” approach to formulating Product Backlog Items and how it can be implemented to improve the communication of user value and the overall quality of the product by facilitating a user-centric approach to development.

Consider the following

User stories trace their origins to eXtreme Programming, another Agile method with many similarities to Scrum. Scrum teams often employ aspects of eXtreme Programming, including user stories as well as engineering practices such as refactoring, test-driven development (TDD) and pair programming to name a few. In future modules of this program, you will have the opportunity to become familiar enough with some of these practices in order to understand their importance in delivering quality products and how you can encourage your team to develop them. For now, we will concentrate on the capability of writing good user stories.

The Three ‘C’si

A User Story has three primary components, each of which begin with the letter ‘C’:


  • The Card, or written text of the User Story is best understood as an invitation to conversation. This is an important concept, as it fosters the understanding that in Scrum, you don’t have to have all of the Product Backlog Items written out perfectly “up front”, before you bring them to the team. It acknowledges that the customer and the team will be discovering the underlying business/system needed as they are working on it. This discovery occurs through conversation and collaboration around user stories.
  • The Card is usually follows the format similar to the one below

As a <user role> of the product,

I can <action>

So that <benefit>.

  • In other words, the written text of the story, the invitation to a conversation, must address the “who”, “what” and “why” of the story.
  • Note that there are two schools of thought on who the <benefit> should be for. Interactive design specialists (like Alan Cooper) tell us that everything needs to be geared towards not only the user but a user Persona with a name, photo, bio, etc. Other experts who are more focused on the testability of the business solution (like Gojko Adzic) say that the benefit should directly address an explicit business goal. Imagine if you could do both at once! You can, and this will be discussed further in more advanced modules.


  • The collaborative conversation facilitated by the Product Owner which involves all stakeholders and the team.
  • As much as possible, this is an in-person conversation.
  • The conversation is where the real value of the story lies and the written Card should be adjusted to reflect the current shared understanding of this conversation.
  • This conversation is mostly verbal but most often supported by documentation and ideally automated tests of various sorts (e.g. Acceptance Tests).


  • The Product Owner must confirm that the story is complete before it can be considered “done”
  • The team and the Product Owner check the “doneness” of each story in light of the Team’s current definition of “done”
  • Specific acceptance criteria that is different from the current definition of “done” can be established for individual stories, but the current criteria must be well understood and agreed to by the Team.  All associated acceptance tests should be in a passing state.


The test for determining whether or not a story is well understood and ready for the team to begin working on it is the INVEST acronym:

I – Independent

  • The solution can be implemented by the team independently of other stories.  The team should be expected to break technical dependencies as often as possible – this may take some creative thinking and problem solving as well as the Agile technical practices such as refactoring.

N – Negotiable

  • The scope of work should have some flex and not be pinned down like a traditional requirements specification.  As well, the solution for the story is not prescribed by the story and is open to discussion and collaboration, with the final decision for technical implementation being reserved for the Development Team.

V – Valuable

  • The business value of the story, the “why”, should be clearly understood by all. Note that the “why” does not necessarily need to be from the perspective of the user. “Why” can address a business need of the customer without necessarily providing a direct, valuable result to the end user. All stories should be connected to clear business goals.  This does not mean that a single user story needs to be a marketable feature on its own.

E – Estimable

  • The team should understand the story well enough to be able estimate the complexity of the work and the effort required to deliver the story as a potentially shippable increment of functionality.  This does not mean that the team needs to understand all the details of implementation in order to estimate the user story.

S – Small

  • The item should be small enough that the team can deliver a potentially shippable increment of functionality within a single Sprint. In fact, this should be considered as the maximum size allowable for any Product Backlog Item as it gets close to the top of the Product Backlog.  This is part of the concept of Product Backlog refinement that is an ongoing aspect of the work of the Scrum Team.

T – Testable

  • Everyone should understand and agree on how the completion of the story will be verified. The definition of “done” is one way of establishing this. If everyone agrees that the story can be implemented in a way that satisfies the current definition of “done” in a single Sprint and this definition of “done” includes some kind of user acceptance test, then the story can be considered testable.

Note: The INVEST criteria can be applied to any Product Backlog Item, even those that aren’t written as User Stories.

Splitting Stories:

Sometimes a user story is too big to fit into a Sprint. Some ways of splitting a story include:

  • Split by process step
  • Split by I/O channel
  • Split by user options
  • Split by role/persona
  • Split by data range

WARNING: Do not split stories by system, component, architectural layer or development process as this will conflict with the teams definition of “done” and undermine the ability of the team to deliver potentially shippable software every Sprint.


Like User Stories, Personas are a tool for interactive design. The purpose of personas is to develop a precise description of our user and so that we can develop stories that describe what he wishes to accomplish. In other words, a persona is a much more developed and specific “who” for our stories. The more specific we make our personas, the more effective they are as design tools.iii

Each of our fictional but specific users should have the following information:

  • Name
  • Occupation
  • Relationship to product
  • Interest & personality
  • Photo

Only one persona should be the primary persona and we should always build for the primary persona. User story cards using personas replace the user role with the persona:


can <action>

so that <benefit>.


i The Card, Conversation, Confirmation model was first proposed by Ron Jeffries in 2001.

ii INVEST in Good Stories, and SMART Tasks. Bill Wake. http://xp123.com/articles/invest-in-good-stories-and-smart-tasks/

iii The Inmates are Running the Asylum. Alan Cooper. Sams Publishing. 1999. pp. 123-128.

Please share!

The Agile Framework: Agile Values and Principles, The Agile Toolkit, The Agile Organization

Learn more about transforming people, process and culture with the Real Agility Program

When I am speaking with executives, ScrumMasters and other leaders of change in organizations, I often present a simple 3-layer model to understand the relationship between the various moving parts in the Agile Framework:

  1. The Agile Values and Principles – These describe the culture and, in the Agile Manifesto, are the definition of the word “Agile” as applied to software development. I didn’t write the Agile Manifesto so I don’t get to re-define the word Agile.  To give an example: in the manifesto it says “The best architectures, requirements and designs emerge out of self-organizing teams.”  As a former enterprise architect at Charles Schwab, I struggled with what I saw as incredibly wasteful up-front architectural activities when I knew that developers would (sometimes) ignore my glorious ivory-tower plans!  Therefore, if you are still doing up-front architecture and forcing your teams to comply to that architecture, you aren’t Agile.  Therefore, as an individual, a team or an organization, you need to make a conscious decision to “BE” Agile or not… and if you decide not, then please don’t call yourselves Agile.
  2. The Agile Toolkit – There are many hundreds of distinct tools in the Agile toolkit including Scrum, OpenAgile and other “large” Agile methods, as well as the Planning Game, Product Box, Test-Driven Development and other “small” Agile techniques.  Any group of people trying to BE Agile, will need to use dozens or even hundreds of different Agile tools.  I call them tools because the analogy with construction tools is a very good one.  Scrum is like a hammer.  But you can’t do much with just a hammer.  Scrum is a great, simple tool.  But you always need other tools as well to actually get stuff done.  All the tools in the Agile Toolkit are compatible with the Agile Values and Principles.  Even so, it is possible to use the Agile Tools without being Agile.  A Scrum team that never gets together face-to-face is not an Agile team: “The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”  (Video conferencing doesn’t count.)
  3. The Agile Organization – When you start using a tool, there is a learning period.  We start by being conscious of our incompetence and as we persist, we become competent… but it isn’t natural or habitual yet.  Eventually, with continued use, we become unconscious of the tool.  IDE’s and version control are like this in most organizations: we don’t even think about them!  But getting through that initial stage requires us to change; to develop new skills.  This process usually requires discomfort or pain (including psychological pain).  An organization attempting to BE Agile and to use many of the tools in the Agile Toolkit will need to make many changes and often these will be difficult.  For example, incorporating the Product Owner role from Scrum into your organization requires new role definitions, new performance evaluation practices and criteria, new compensation systems, new communication and reporting mechanisms, new authority and accountability processes, etc. etc.  All of the changes required are about creating Enterprise Agility throughout the whole organization, beyond just software or IT.  These extensive changes are often started in a very ad hoc manner, but at some point they need to become systematic.  This is an important decision point for executive management: are we going to be Pragmatic about our Enterprise Agile adoption, or are we going to be Transformative about our Enterprise Agile adoption.

All of this is summarized in this graphic:

The Agile Framework [PDF]

I sometimes also call this the “Agile Ecosystem” since it is a constantly evolving set of ideas (processes, tools, resources) that does not have a clearly defined boundary.  For example, the technique of Value Stream Mapping comes from Lean manufacturing but has also be broadly adopted by Agile practitioners.

Please share!

Good Explanation of INVEST for User Stories

Learn more about transforming people, process and culture with the Real Agility Program

Mike Caspar, a fellow agile coach,  just forwarded me this YouTube video to Bill Wake talking about INVEST for User Stories.  I worked briefly with Bill back in 2004/2005 at Capital One where he did some excellent coaching.  I strongly recommend checking out the video!

Please share!

ANN: June Agile Software Engineering Practices

Learn more about transforming people, process and culture with the Real Agility Program

Isráfíl Consulting Services is pleased to announce our upcoming:

Agile Software Engineering Practices Courses (2 day)

Software Developers, Technical Architects and Lead Developers for teams that currently use or are intending to use Agile methods such as Scrum, Extreme Programming or OpenAgile will benefit from attending this course.
After completing this course you will:

  • increase your development productivity
  • be familiar with basic disciplines to create well-tested, defect-free code
  • be able to integrate successfully into Agile teams
  • understand what makes healthy, maintainable code
  • receive a Certificate of Attendance
  • receive $100.00 discount on a 3-day Scrum training and certification course by our partners

Available Classes:

  • 2009-06-22: 2-day Agile Software Engineering Practices – Ottawa, ON $1450.00 CAD [16 spaces]
    • Register by June 1 and get the early-bird price of $1,250.00.
  • 2009-06-25: 2-day Agile Software Engineering Practices – Markham, ON $1450.00 CAD [16 spaces]
    • Register by June 1 and get the early-bird price of $1,250.00.

Register!: http://www.israfil.net/publictraining/registerCourse Details: http://www.israfil.net/publictraining/coursesClass Schedules: http://www.israfil.net/publictraining/scheduleFor more information, please e-mail us at: training@israfil.net

Please share!

ANN: Agile Software Engineering Practices training by Isráfíl Consulting

Learn more about transforming people, process and culture with the Real Agility Program

Isráfíl Consulting is finally prepared for the first series of its Agile Software Engineering Practices training courses. This series is offered in partnership with Berteig Consulting who are graciously hosting the registration process. Their team has also helped greatly in shaping the presentation style and structure of the course. The initial run will be in Ottawa, Toronto (Markham), and Kitchener/Waterloo.   

Topics covered will include Test Driven Development (TDD), testability, supportive infrastructure such as build and continuous integration, team metrics, incremental design and evolutionary architecture, dependency injection, and so much more. (This course won’t present the planning side of XP, but covers many other aspects common to XP projects) It makes a great complement for training in Agile Processes such as XP, Scrum, or OpenAgile. The overview slide presentation is available for free download from the Isráfíl web site.

The courses are scheduled for:

The course is $1250 CAD per student, and participants receive a transferrable discount of $100 CAD for other training with Berteig Consulting as a part of our ongoing partnership. I initially prototyped this course in Ottawa this December, and am very excited to see this through in several locales. Class size is limited to 15, so we can keep the instruction style more involved. The above schedules are linked to Berteig Consulting’s course system and have registration links at the bottom of the description. Locations are TBD, but will be updated at the above links as soon as they’re finalized.

A further series is planned for several US cities in March, and we’ll be sure to announce them as well.

Please share!

Yet another misunderstanding of TDD, testing, and code coverage

Learn more about transforming people, process and culture with the Real Agility Program

I was vaguely annoyed to see this blog article featured in JavaLobby’s recent mailout. Not because Kevin Pang doesn’t make some good points about the limits of code coverage, but because his title is needlessly controversial. And, because JavaLobby is engaging in some agile-baiting by publishing it without some editorial restraint.

In asking the question, “Is code coverage all that useful,” he asserts at the beginning of his article that Test Driven Development (TDD) proponents “often tend to push code coverage as a useful metric for gauging how well tested an application is.” This statement is true, but the remainder of the blog post takes apart code coverage as a valid “one true metric,” a claim that TDD proponents don’t make, except in Kevin’s interpretation.

He further asserts that “100% code coverage has long been the ultimate goal of testing fanatics.” This isn’t true. High code coverage is a desired attribute of a well tested system, but the goal is to have a fully and sufficiently tested system. Code coverage is indicative, but not proof, of a well-tested system. How do I mean that? Any system whose authors have taken the time to sufficiently test it such that it gets > 95% code coverage is likely (in my experience) thinking through how to test their system in order to fully express its happy paths, edge cases, etc. However, the code coverage here is a symptom, not a cause, of a well-tested system. And the metric can be gamed. Actually, when imposed as a management quality criterion, it usually is gamed. Good metrics should confirm a result obtained by other means, or provide leading indicators. Few numeric measurements are subtle enough to really drive system development.

Having said that, I have used code-coverage in this way, but in context, as I’ll mention later in this post.

Kevin provides example code similar to the following:

String foo(boolean condition) {
    if (condition)
        return "true";
        return "false";

… and talks about how if the unit tests are only testing the true path, then this is only working on 50% coverage. Good so far. But then he goes on to express that “code coverage only tells us what was executed by our unit tests, not what executed correctly.” He is carefully telling us that a unit test executing a line doesn’t guarantee that the line is working as intended. Um… that’s obvious. And if the tests didn’t pass correctly, then the line should not be considered covered. It seems there are some unclear assumptions on how testing needs to work, so let me get some assertions out of the way…

  1. Code coverage is only meaningful in the context of well-written tests. It doesn’t save you from crappy tests.
  2. Code coverage should only be measured on a line/branch if the covering tests are passing.
  3. Code coverage suggests insufficiency, but doesn’t guarantee sufficiency.
  4. Test-driven code will likely have the symptom of nearly perfect coverage.
  5. Test-driven code will be sufficiently tested, because the author wrote all the tests that form, in full, the requirements/spec of that code.
  6. Perfectly covered code will not necessarily be sufficiently tested.

What I’m driving at is that Kevin is arguing against something entirely different than that which TDD proponents argue. He’s arguing against a common misunderstanding of how TDD works. On point 1 he and I are in agreement. Many of his commentators mention #3 (and he states it in various ways himself). His description of what code coverage doesn’t give you is absurd when you take #2 into account (we assume that a line of covered code is only covered if the covering test is passing). But most importantly – “TDD proponents” would, in my experience, find this whole line of explanation rather irrelevant, as it is an argument against code-coverage as a single metric for code quality, and they would attempt to achieve code quality through thoroughness of testing by driving the development through tests. TDD is a design methodology, not a testing methodology. You just get tests as side-effect artifacts of the approach. Useful in their own right? Sure, but it’s only sort of the point. It isn’t just writing the tests-first.

In other words – TDD implies high or perfect coverage. But the inverse is not necessarily true.

How do you achieve thoroughness by driving your development with tests? You imagine the functionality you need next (your next increment of useful change), and you write or modify your tests to “require” the new piece of functionality. They you write it, then you go green. Code coverage doesn’t enter into it, because you should have near perfect coverage at all times by implication, because every new piece of functionality you develop is preceded by tests which test its main paths and error states, upper and lower bounds, etc. Code coverage in this model is a great way to notice that you screwed up and missed something, but nothing else.

So, is code-coverage useful? Heck yeah! I’ve used coverage to discover lots of waste in my system. I’ve removed whole sets of APIs that were “just in case I need them” APIs, because they become rote (lots of accessors/mutators that are not called in normal operations). Is code coverage the only way I would find them? No. If I’m dealing with a system that wasn’t driven with tests, or was poorly tested in general, I may use coverage as a quick health meter, but probably not. Going from zero to 90% on legacy code is likely to be less valuable than just re-writing whole subsystems using TDD… and often more expensive.

Regardless, while Kevin is formally asking “is code coverage useful?” he’s really asking (rhetorically) is it reasonable to worship code coverage as the primary metric. But if no one’s asserting the positive, why is he questioning it? He may be dealing with a lot of people with misunderstandings of how TDD works. He could be dealing with metrics bigots. He could be dealing with management-imposed-metrics initiatives which often fail. It might be a pet peeve or he’s annoyed with TDD and this is a great way to do some agile-baiting of his own. I don’t know him, so I can’t say. His comments seem reasonable, so I assume no ill intent. But the answer to his rhetorical question is “yes, but in context.” Not surprising, since most rhetorically asked questions are answerable in this fashion. Hopefully it’s a bit clearer where it’s useful (and where/how) it’s not.

(This article is a cross-post from “Geek in a Suit”)

Please share!

Comprehensive List of Agile Practices

Learn more about transforming people, process and culture with the Real Agility Program

This might be impossible, but I was thinking that it would be cool to have a single reference of all the possible agile practices.  Obviously, since “agile” is not a single defined method, we must take the word “comprehensive” with a bit of humor (or a grain of salt).  I’ve attached a spreadsheet that represents my first draft (it’s in OpenOffice.org format so that you don’t have to worry about me spreading viruses – if you want it in MS Office format, email me at mishkin@berteigconsulting.com).  I’ve split the practices up into several sections including: “Agile Skeleton”, “Common Practices”, “Basic Scrum Practices”, “Optional Scrum Practices”, “Extreme Programming Practices” and “Lean Practices”.  I’ve stopped there because I’m not an expert on other agile methods such as Crystal, Agile Unified Process or Feature Driven Development.  I imagine that this list will be useful for teams to do self-assessment and to think about ways they might improve.  Perhaps it could be used in a retrospective setting.  Berteig Consulting coaches use something similar to this to assess the effectiveness of their engagement with clients.  If you think of practices I’ve missed or other potential uses for a list like this, let me know in the comments.  My intention is to convert this to a wiki and make it available under a Creative Commons license once it is a little more refined.

Agile Practices Adoption Worksheet (OpenOffice format – 68KB)


Please share!

Agile Blogs

Learn more about transforming people, process and culture with the Real Agility Program

There’s a great discussion on the Extreme Programming Yahoo! group where a whole bunch of folks list their blogs out. If you aren’t part of the group, you should probably join it (it focuses on technical practices, and there’s lots of other good agile stuff there too). The discussion starts with a message from James Carr where he asks who else here blogs?

It’s probably still cool to jump in with your own blog link if you have an agile-focused blog (I’m sure Scrum, Lean and other agile methods would be welcome even though it’s an extreme programming list!)

Please share!

Excellent Article about Planning Velocity

Learn more about transforming people, process and culture with the Real Agility Program

J. B. Rainsberger has written an excellent article about the usefulness of planning velocity (and the places where it is not useful as well). I highly recommend reading it, particularly if you are a manager or a project manager.

Please share!