Thursday, April 10, 2008

CHAPTER 3: Communicating and Collaborating

3.1 Introduction

Communication is considered to be the main factor in a project’s success or failure. Alistair Cockburn calls software development “a game of communication and invention”, in his book “Agile Software Development”, where a big part is dedicated to explaining communication problems and how communication influences the development of a software project. In all agile methodologies, communication and close collaboration with the customer is emphasized as a “must do” practice; in XP two of the five values are communication and feedback, in SCRUM’s values we can find communication, Crystal comes with osmotic communication between team members and with early access to expert users and so on.

Bad communication between the different people involved directly in a software project, can create a lot of overhead and waste important resources, and in many cases can cause the failure of the project. For this reason, all software methodologies have developed more standards for communicating, formal and informal, while working on a project, between the different stakeholders.

Communication can be divided in: communication inside the development team and communication outside the development team, with the customer and with the upper management.

3.2 Communicating with the customer

3.2.1 Requirements

Functional specification documents signed off at the beginning

Traditional software methodologies need to gather the client’s requirements at the beginning of the project, putting everything in a big functional specification document that needs to be signed off by the client before it can go into production. This approach seems fair and quite straightforward but practice over the years has shown that it can have some very serious flaws. The biggest problem with this approach is that due to the problems in understanding software and how it works, the customer cannot always tell what he wants from the beginning, and might miss some very important aspects when the functional specification document is signed off.

There have been numerous cases in the past when projects were developed within budget, delivered on time and as asked for, by the functional specification document, but when put into production they were completely useless for the customer. Yes, the customer could be blamed for not knowing what he wants when he needs to, but the pure fact is that he is unhappy about paying for unusable software. A customer that had such an experience will be very reluctant when needing to sign off another functional specification document and in many cases a lot of overhead will be generated in development because of his fear of being forced to pay for unusable software.

Although big functional specification documents seem very good to the untrained eye, they do have serious flaws:

- They are very costly to build (how much time do you need to write 100-600 pages of text?)

- They might miss important aspects of the program. Written text is not very good at communicating things. The writer cannot capture whatever he needs to capture and the one that reads tends to imagine the rest. Imagination is good, but not in this case because, in this case, it is very costly.

- They tend to push the customer proxy. The more indirection and steps trough which something goes from the customer to the actual developer building the software, the more misunderstandings can, and usually do occur. When the information needs several nodes to be transmitted from the ones that know the business to the one that builds the program, important time is lost, and important precision.

- Big documents are hard to read. Someone might say it is important to capture everything there otherwise programmers would complain about not being complete, but over completing it is just as bad.

- What if something changes? What if at the time the document was written there was one situation and it just changed? What do you do? Throw up the part or the entire document? If you wrote it in 1 month, and it cost you x, you have just lost a 10-20-30-...100% of x and need to pay again for the new one.

Big functional documents are written to replace trust between the parties involved. We need to write everything in the specification document and cast it in stone, so it can't change and we can't be held responsible by the customer later. Where there isn’t trust, there isn't good business. Lack of trust is usually compensated with enormous overhead in work and cost. But on the other hand, not everyone is to be trusted.

Agile requirements

Mike Cohn wrote in User Stories Applied []:

I felt guilty throughout much of the mid-1990s.[...]

I knew that what we were doing worked. Yet I had this nagging feeling that if we'd write big, lengthy requirements documents we could be even more successful. After all, that was what was being written in the books and articles I was reading at the time. If the successful software development teams were writing glorious requirements documents then it seemed like we should do the same. But, we never had the time. Our projects were always too important and were needed too soon for us to delay them at the start.

Because we never had the time to write a beautiful, lengthy requirements document, we settled on a way of working in which we would talk with our users. Rather than writing things down, passing them back and forth, and negotiating while the clock ran out, we talked. We'd draw screen samples on paper, sometimes we'd prototype, often we'd code a little and then show the intended users what we'd coded. At least once a month we'd grab a representative set of users and show them exactly what had been coded. By staying close to our users and by showing them progress in small pieces, we had found away to be successful without the beautiful requirements documents.

Agile methodologies have developed methods to capture requirements in such a way that the problems and risks associated with the methods presented above are very well addressed. Agile thinking works with the fact that requirements change in time and works with human nature, allowing the customer not to know exactly what he wants from the beginning. In every agile methodology, a very strong emphasis is put on close and direct communication with the customer, so the misunderstandings generated by customer proxies are eliminated. The most efficient methods of communication are used: verbal, real-time, face to face communication is pushed forward against written documentation, which is kept to a minimum.

Intermediate work products (documentation, use cases, UML diagrams, database schemas etc) are not important models of reality, nor do they have intrinsic value. They have value only as they help the team make a move in the game. Thus, there is no idea to measure intermediate work products for completeness or perfection. An intermediate work product is to be measured for sufficiency: Is it sufficient to remind or inspire the involved group?

[Alistair Cockburn, 2003]

User stories, backlog items, acceptance tests

Since the emphasis is put on close collaboration and face to face, real time communication with the customer, written requirements are kept as brief as possible. They usually act mostly like a reminder of a thing that needs to be discussed between the customer and the developers.

The most well known ways to capture requirements from the customer in agile methodologies are the user stories, originating from XP and the backlog items, originating from SCRUM. Both describe functionality that will be valuable to the customer and the users of the system.

Mike Cohn defines in ‘User Stories Applied’ [], the following characteristics of a good user story: independent, negotiable, valuable to users or customers, estimable, small and testable.

Because of their light nature, user stories and backlog items act more like an instrument used for planning, than for describing what is wanted. They give the directives on what is wanted and the details are mostly discussed with the customer and expressed as acceptance tests.

Acceptance tests are a feedback mechanism defined by the customers (with the help of programmers) to allow programmers to know if a feature has been finished and if that feature has been implemented exactly as the customer wants it. Instead of making the customer describe what he wants, acceptance tests are built by asking the customer: “how will I know that what we did is according to what you want?”. And he will start saying what needs to be done, for him to be able to know if what was requested was built and finished or not. Instead of heavy descriptions, two purposes are achieved by this question: you know what needs to be done and you know how you can test, at the same time. Also, ambiguity tends to be dissolved by acceptance tests, because the customer, in order to know how to test something, he must have a very intimate knowledge and understanding of that thing.

The user story mini-sample

Case 1: Requirements document

4.3 Outstanding contracts report

The system will allow the users to see a report of outstanding contracts. An outstanding contract is a contract that exceeds a predefined number of days, since it has been sent to the customer and no response has been received.

The outstanding contacts page:

Contract management system

My contracts (1) Reports (2)

Outstanding contract report

Choose the number of days: [ (3)] [Search] (4)


Customer (5)

Contract reference (6)

Number of days passed (7)

Customer #1

Ref #1


Customer #2

Ref #2


Customer #3

Ref #3






My contracts

Description: Menu item (-the) will allows navigation to the page where my contracts can be managed



Description: Allows user to navigate to the reports screen where all reports reside


Number of days

Description: Allows entry of the number of days that need to be exceeded so that the contract will be displayed.

Function: User types the number of days as an integer value


Search button

Description: Allows the query to be performed

Function: On click the system will search the database for the contracts specified and will display them in the table below the button on finish. If no results have been found then a message “No search results.” will be displayed



Description: Displays the customer name


Contract Reference

Description: Displays the contract reference number


Number of days passed

Description: Displays the number of days that have passed since the contract was sent to the customer

Case 2: User story and acceptance test

Outstanding contracts report

Report all contracts sent to the customer and no answer was received for a number of days above a given amount.

Acceptance test

For a list of contracts:



Sent date







Coca Cola











Test case 1: Filtering at 2005.10.20, for contracts above 100 days would result in:

No results to display.

Test case 2: Filtering at 2006.04.20, for contracts above 15 days would result in:


Contract reference

No of days passed




Test case 3: At 2006.04.30 for 10 days:


Contract reference

No of days passed







3.2.2 Set-based development

Communicating the requirements can be done in two ways: communicating the constraints, allowing multiple solutions to be developed by the programmers until one emerges or communicates the solution, and refining it until it works. Mary Poppendieck calls this: set based vs. point based development.

As a simple example, the customer can say: we need a desktop application that enables us to see our sales or we need a way to see our sales. The first thing enforces a desktop application solution, while the second allows the possibility to develop more solutions: web based, desktop based, mobile etc. If the second requirement is detailed as: we need to be able to see our orders real-time, as quickly as possible as some of them need a sales manager’s approval, and he needs to do that no matter where he is, then suddenly, the mobile solution might seem like a better solution, having the mobility constraint. Further defining the constraints, one solution will emerge. If we take the point based approach going directly on a desktop application, when the mobility constraints is revealed we might be forced to go back and rethink the desktop solution, throwing away the desktop solution code.

Agile methodologies have built in their practices ways to communicate and implement, using set based development like: developing multiple solutions in the early iterations and letting one emerge, communicating constraints instead of solutions , a very good example being acceptance tests which communicate testing constraints not solutions for implementation and design for change, where extensive refactorings, and fast changes and shifts based on constraints can let a solution emerge from a larger range of possibilities.

3.2.3 Feedback

Customer feedback

It's two in the morning and you are driving home. The traffic light is red, and there's not another car in sight. But the traffic light is red, so you stop. And wait. And wait. Finally, the light changes, after allowing time for lots of nonexistent cross-traffic. You think to yourself, it’s going to be a long drive home. And sure enough, the next light is also red. But as you approach the light, it turns green. Ah ha! you think, An automatic sensor. That light is smart enough to know I'm here and there's no one else around. I hope the rest of the lights are like that!

The difference between the two lights is feedback. The first light was preprogrammed.

[Poppendieck 2003]

Improvement can only be done as a result of feedback. The development team writes a piece of the system, the customer sees it and tells them if that program is good or not. He can also tell the developers what would be even more liable to improve the program’s quality.

The virtual nature of software makes it very hard for customers to understand how it’s build and done, so it is very hard for them to communicate you what they really want. To address this extremely important problem, software should be shown very often to the customer. This has two very important benefits:

- he can see where you are, the real progress, and this increases his trust that you’re doing what you were planning to do and that his money is not wasted

- he can see if something is not what he wanted and tell the development team, so they can fix it or after seeing it he can start to ‘feel’ the software and be able to give you much better information about what he wants. The smaller the delivery cycles, the better.

The small delivery cycles are incredibly important in a project’s communication. As previously stated they show one very good technique to avoid derailing the project and they embrace changing requirements.

When the first requirements are being gathered from the customer, the developers explain him how something can be done, but it is very easy for him to imagine a completely different thing. It is also very hard for him to understand what can and what cannot be done; why something costs more or what costs less. After the team delivers the first result of an iteration, he can see a computer program, and everything seems to take shape in his mind. He can use this as a basis for future requirements, and can see about how much time one thing or another takes to be implemented. The second iteration is even better and as the project progresses, the dark fog that the software seemed to be in the beginning is starting to become clearer, easier to control and he becomes less and less stressed. He starts to understand how things are done and he sees real progress. There is nothing more honest than showing the customer the real program from which he can see the progress.

Code feedback

If feedback is the base for all improvement, how can feedback help the internal quality of a project? What we discussed earlier about feedback is the external quality that can be improved, the part that the customer understands and helps improving, but what about internal quality. But what is internal quality in a software project?

A project is of high internal quality if it can be tested and debugged easily and it can change with very little effort. Being able to be changed easily assures the program a much longer life in production, which makes it cheaper. If the customer pays $1.000.000 for a software and the software is used for 5 years, it will cost $200.000 every year. If the same software can be fixed, readapted and maintained longer in usage, for instance for 10 years, it costs $100.000 per year. Twice cheaper, isn’t it?

But how can we make the software give us feedback about its health? In agile methodologies the best technique for receiving feedback from the code itself about its health are automated tests. They can detect problems very early and report them to the developers so they can act very fast on them. The automated tests become break detectors. If the developers can detect breaks in the existing functionality fast, they can fix them fast and that allows them a great flexibility. A programmer makes a change in the software, even in the code he didn’t write. Then he runs the tests. If they detect a break, he knows it and he can choose either to reverse the change or repair the affected part.

A big problem in a program’s flexibility is that if it becomes big, it is very rigid, and making a change can affect parts of it that cannot be easily predicted. So the developers are afraid to change it. So the project starts to be doomed. The hardest it is to be changed, the hardest it is for it to cope with the market requirements so the shorter its life will be. Having an army of break detectors as automated tests ensure great flexibility, diminishes fear of change, even in big and complex systems, because of the fact that they can give the developers feedback about their actions very fast.

3.2.4 Showing progress

Working software doesn’t lie. One of the agile manifesto principles states: “Working software is the primary measure of progress”. Showing the customer the product instead of reports after each iteration is completed (2-4 weeks), is a great way to communicate progress and to build a product of much bigger value to the customer. Putting that software into production every few months and seeing how it is used, collecting what the users think can improve the software, can build thrust between the client and the programmers, driving the software to success.

For communication inside the team or with upper management, big visible charts on a wall, showing very clearly the features implemented, and the features not implemented can be a very effective and silent technique to show everyone passing by that wall, the current status of a project.

3.3 Communicating inside the team

The project related information must go very fast inside the team. Crystal calls this osmotic communication and it is at the very core of the methodology. It says that people working on the same project need to be able to use the best communication technique: face to face communication, with and without a whiteboard. For this the best technique is to have the entire team collocated in the same room as much as possible , all facing each other, to be able to ask each other questions and to enable others to hear discussions etc. The team must also have a whiteboard in their proximity where they can design or use sketches on the whiteboard to communicate better.

Extreme Programming goes even further, addressing the communication problem mainly with user stories written on pieces of paper and stuck to the wall, and with writing all the business code by pair programming. This means that two programmers, work together at the same computer, understanding 100% of what’s done, and not 50% as if they were doing it separately.

The techniques above and others mainly address communication when time is crucial, but there are other problems of communication within the organization, where time is not that crucial. This is best described by a situation, where a team is developing a program for a few months, delivering it to the client in the end. Now the client wants to continue the development of the program, to add extensions to it, to improve certain parts etc, but the team that built it is not available anymore or it is partially available. How will the new programmers who come in contact with the program understand what was required, what was done, and how it was done?

Extreme Programming comes up and says that the best way to document a computer program is the code itself and the automated tests, it has and not documents describing what was done, as these documents need to be written by someone, which is costly and becomes obsolete very soon. In most cases, I find this approach very good, as I noticed that, recently, whenever I download an open source framework or look at a code written in the past, the first thing I instinctually do when I want to learn how to use it, is to look at the unit tests. They show me how the software can be used, and which the limitations are, in the same language I want to use it: code.

3.4 Improving communication: quantity vs. quality

If communication plays such an important role in all aspects then how can we improve it? For the sake of improving communication, many people fall into a very big trap, believing that improving communication means increasing quantity: more meetings, more documentation, more emails and more phone calls. This is profoundly wrong: communication can only be improved by quality and in many cases improving quantity means increasing the communication problem and not solving it.

Meetings are failures when participants leave the meeting feeling no productive results were achieved; or, that the results that were derived were accomplished without the full engagement of the participants. In short, these useless meetings do not engage collaboration and participative decision making.

[ Booch and Brown, Collaborative Development Environments]

In order to improve the quality of communication we must see which types of communication are better then others. Following this idea, Alistair Cockburn, makes a communication top in Agile Software Development, concluding that Interactive, face-to-face communication is the cheapest and fastest channel for exchanging information.

If verbal, face to face communication is not at hand but there are other great ways to deal with it, like visual communication, web based collaboration tools acting as whiteboards and allowing people to chat real-time, application sharing, instant messengers, etc.

As an example of visual communication, a single screenshot can show even the context in which a bug appeared and give the developers a great deal of information about the user actions. Screenshots or even small recorded movies of user actions, are very cheap, and communicate a lot of useful information, which in some cases might be missed just by sending a plain text email or document.

Another example of improving communication are customer improvement programs where the user is either asked to add suggestions on how he would like a program to be improved or when a bug appears the software automatically detects it and sends by email or other means, information (maybe even screenshots) about the problem to the developers to be analyzed and the problem solved.

Macromedia Flash recorded movies are becoming a more and more popular way to show how software can be used instead of plain text or “classical” help documents, because their visual nature enhances the experience the user has when learning about the program.

Table based communication is one of the most used at this time in businesses (mostly due to Microsoft Excel) because of its simplicity and concreteness. The same approach has been brought into software development by Ward Cunningham, who invented a brilliant communication, organization and testing tool based on tables called Fit ( ). Fit is a great framework for acceptance tests. His work is now continued by a wiki concepts based tool developed at ObjectMentor, being supervised by Robert C. Martin, called Fitnesse ( ).

New ways of enhancing communication are emerging, allowing people to communicate better, thus making them able to collaborate closely even if they are not situated in the same room, and obtaining better software.

No comments: