Thinking about documentation

In working these days in a presentation I'll be doing with a peer on "Requirements in eXtreme Programming". I'm taking a course about Requirements Engineering with a strong focus in RUPs way of doing requirements, so guess it'll be important to address the topic of why XP does so little documentation.

In the Art of Agile Development, James Shore explains the 3 types of documentation:
- Work In Progress Documentation: helps you to get your job done.
- Product Documentation: documents that provide business value
- Handoff Documentation: documents for handing off the project to a new team

Requirements documents and design documents are usually just work-in-progress documentation. The real need is how can we communicate while we develop software. XP emphasizes a whole team (customer, programmer, testers) that sits together, communicates face to face and shares a common language (ubiquitous language).

I agree completely in that oral communication is much more effective than just receiving a document (use case or any other) with a task that says "Program it". What if instead of giving documents to our programmers we give them a brief statement of what need to be done and then they have the chance to get the requirements directly with the customer? That is the idea of using user stories. They are work-in-progress artifacts. They are not little requirements documents, but they replace them with a cool combination:

On Site Customer + User Stories + Common Domain Language + Iterative Development (program byte-sized requirements) + Automated Tests (unit and customer tests)

I thought that User stories were just a lazy way of not writing use cases (or SRSs) but actually they are a smart way of remembering that we need to communicate with the customer. XP practices really support each other, so I think that before saying "XP doesn't work for me cause it does so little documentation", we should take a look at how all practices fit together.

A little conclusion: XP supports written communication with other practices that are far more effective than just written documents. (check page 195 inThe Art of Agile Development).

In the next days, I'll be googling, thinking and writing about where do use cases, as a technique, fit in agile. Hope you'll come back and read my findings and opinions!

In the beginning of a new project...

In the beginning of a new project, you wonder what can you do to get better results than in your last, right? Well, actually the most common is to do the same things you did last time and expect to get different results! I think that's nonsense, we should strive every time to improve our process and make our teams more effective. What's effectiveness? For me, is to deliver a product that satisfies the business needs. That's why I like agile processes, they are focussed on delivering business value from week 1.

Last week, the business people handed us some documents they wrote for modeling the business (as in RUP). I'm sure they spent a lot of time writing them. I read them and am required to make a use case model and estimate. Last project we did that and missed by 100%! (the project was estimated in 5 and me took 10)... actually, the first release will be on March... We estimated a with about 50 use cases that we wrote in about 2 months, and we really missed the target. Why? Some aspects are:

- We did a big Requirements Phase upfront. Requirements always change. In the beginning of the project, you really don't know everything! We all learn a lot during the project time, even the user, and requirements always change.
- Sometimes, the developer read the use case and programmed something different from the what the user expected.
- We didn't include enough time for testing.
- Testers weren't part of the projects but after 7 months of development.
- My MS Project has been in 90% for the last 2 months... My schedule is not guarantee or real indicator of the project status, working software is...

In this new project, I want different results, and for that, I think we need to try different things.

The first thing is: Don't do a lot of upfront requirements.

Check this essay from James Shore:
http://jamesshore.com/Blog/Up-Front-Requirements.html

Business people really trust in us!

When you are writing enterprise applications, on most cases you are automating information flow, enforcing business rules and managing persistence. No matter what programming language are you using, you need to understand the business. In this post I wanna share some questions that are in my mind...

1. What is the most difficult stuff about making enterprise applications?
In the applications I'm working on, persistence or UI related stuff is not difficult. The hardest thing is to understand business needs, understand their rules and writing them in a way that a computer can understand. We state our understandings using use cases and other requirements documents, then our business people leave us alone, hoping that we really understood them.

2. How much trust do business people put in our teams?
Wow, I think they trust us a lot! We wrote the use cases, they approved them and after several months without seeing the actual software working, we release the software they'll use. Their jobs depend on us doing the right thing.

3. How do we respond to that trust?
Many times, we as software developers aren't conscious on the critical nature of our software, but we want to make a good product. At my job, we apply some agile practices, but our process relies on a big initial requirements phase and a final testing phase. We use TDD, Continuous Integration, we do code inspections and try to go on with the schedule. Then testers try to understand what the use cases state the software should do and use it in our testing servers. An business people? They are trusting in that the product that they have not seen yet is what they expect. Wow, they trust us so much! BUT maybe, the software works great but isn't what they are expecting. Maybe we automated some calculus but they haven't had a chance to use it with real sample data... We software developers do the best but I think we need one more thing.

4. How do we know that they are confident that their business rules are enforced by the software?
We need to be better in our communication. Let's speak more with the business, let us not rely only in formulas, let's ask the business people for real data examples. Last week I found put that they use Excel a lot for explaining their intents. They can give us many tables of example data. Real data that could assert that our software does what they want.

And that's the goal right? Great software solves real needs. it doesn't matter If software is delivered on time, on budget and according to requirements documents, but isn't what the real users need. Quality is perceived in working software doing the right stuff.

So, as a conclusion, why don't you give users the possibility to give you real examples, use them throughout your development and try everyday to improve your communication. Collaborate more, we are on the same team.

Weekly readlist - Jan 18, 2008

Hi! I'll try to keep a record of some articles I read and share them here. Remember that the sidebar is updated with the most interesting posts I read on of the blogs I follow.

Agile Planning
Our Professional Responsibility

Acceptance Testing
Introduction to FIT
Introduction to Fit and Fitnesse Part I (podcast)
Introduction to Fit and Fitnesse Part II (podcast)
Patterns and Anti-Patterns: Acceptance Testing with FitNesse

Requirements Management
Agile Principle #4: Agile requirements are barely sufficient!

Project management
A Practical Guide to Seven Agile Methodologies

Code generation
NVelocity

NVelocity is a port of the excellent Apache Jakarta Velocity project. It is a very simple, easy to learn and extensible template engine.