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!

Your best friend on the Internet?

Have you noticed that you could spend all day long just reading blogs about your favorite topic? That is cool, but only before you notice that you'll want to know which are the hottest stories and you got a million hits on Google!

That's the cool thing about Social Rank. It helps you to save time by giving you the top stories about your favorite topic. For example, I found www.agiledaily.com, a Social Rank powered website, of course, about agile software development.



I'll give it a try!

Check Top Ten Reasons that Agile Produces Higher Quality

Damon Poold posted Top Ten Reasons that Agile Produces Higher Quality. In my opinion, it's worth to check it out.

TDD Doesn't Make Development Take Longer!

Hi people, tonight I'm thinking about the conception that Test Driven Development makes your project take longer. I googled this post from Jeremy Miller and found it to be based on experience and really match what i've found on my own programming experience.

Some people say that a project can take longer cause you must write and maintain more code, and each time you suggest to include more quality in your software through tests you hear the same objections... but why is that?

Well, I think that is really a natural reaction and seems logical if you haven't developed the test-driven way (red-green-refactor). Some people think they have done TDD but they have just coded automated tests, but TDD is about design and continuous design. If you design the test-first way you are going to finish your code in a faster and better way... that's just a non issue for me. Your code will do what you supposed it should do, no more, no less. Why don't you try yourself? This is a pragmatic issue, if it works why don't we apply it and enjoy the benefits?

Jeremy Miller lists where he thinks TDD cuts development time, and I concur:

- Design
- Debugging
- Fixing bugs
- Testing

Let me add a few, IMHO:

Maintainability: When you develop the TDD way, you can refactor and change your code anytime and just enjoy the simplicity of good code and your unit tests are a safety net. That resumes in few development time and make programming more fun. Also, you can focus more in adding value to the code by reducing technical debt and improving your design cause good tests are you allies.
Trust in your own code: Since the days I started thinking and with TDD I trust much more in my code and feel more proud of it. I can even invite you to take a look any time and even make changes with confidence that my tests validate yours!
Trust in others code: if you honestly did TDD and you trust me your code for working on it, I'll feel very secure that your code will be simple, understandable and open to refactorings. We work in team environments, people come and go, and our code should be always hight quality. We'll save ourselves so much pain...

BUT, (and this is a big BUT), you'll enjoy all that benefits if you're honest and mindful about TDD. Please, don't do it as just a requisite. And PLEASE! Don't say that TDD is an overhead to software development if you haven't given yourself to learning how to do it and practicing for a little while. I can assure you, you won't regret.

If you want, take a look at this Introduction to Test Driven Design (TDD). Enjoy!

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