In
my earlier posts I have written about why should software be documented
and what should we document, and today I will
write about software requirements. Requirements are written documents that describe system that should be
developed and serve as communication
tool between customers and developers. Requirements are also thinking tools that help you understand
what you need to build so you don't waste money building the wrong thing.
"The very act of writing a specification forces you to think through the
design you thought you had in your head, and helps you see the flaws in it
quickly so that you can iterate and try more designs. Teams that use functional
specifications have better designed products, because they had the opportunity
to explore more possible solutions quickly. They also write code faster,
because they have a clearer picture when they start of what’s going to be
needed." [Joel on Software]
Approach to writing requirements
You can organize your requirements in more or less formal or agile fashion but
the main point in requirements isn't the document templates and complex
diagrams. The main point is information. I learned this from few starting
chapters of Writing Effective Use Cases (Alistair
Cockburn). I was expecting to find template for Use Cases that will help me
write better documentation, and instead I found out that approach to writing documentation is more important than document
template.
We
programmers usually see use cases as boring part of work that is holding back
real work and we have urge to begin coding as soon as possible. What happens is
that we don't really analyze
requirements, we just write them down and discover errors in requirements when
coding when we already spent solid amount of our time building the wrong
thing ("Hmmm, this drop down list shouldn't be here..."). If we took time
to think about requirements before implementing them, evaluated hidden problems
and scenarios and validated basic business values defined in
project vision, we could detect errors earlier and
have more stable requirements which in the end lead to better code and happier
programmer life.
Amount of written requirements
Having no requirements is not a good idea and you can not use agile
methodologies as excuse for it. Writing a functional specification is at the
very heart of agile development, because it lets you iterate rapidly over many
possible designs before you write code. Also r
equirement gold-plating is
another extreme approach that leads to
waterfall software development and
many of its problems. As always
there is no silver bullet, you have to find solution
that works for you.
There
are lots of things that can be documented in software development. That doesn't
mean that you should document them all. You should document things that are
important and specific, things that everybody working on project should know
and that you will forget if you don't write them down. Most important
things that should be documented are:
- project vision
- requirements
- architecture and code
Project Vision
"The
Vision summarizes the "vision" of the project. It servers to communicate
the big ideas regarding why the project was proposed, what the problems are,
who the customers are, what they need,
and what the proposed solution looks like. The vision defines the customer’s
view of the product to be developed, specified in terms of the key needs and features.
Containing an outline of the envisioned core requirements, it provides
contractual basis for the more detailed technical requirements." [Craig Larman, Applying UML and Patterns]
Project
vision can be one page document describing why is project being built, what are
customer needs and what is the firm’s benefit. Once project vision is
clear to all team members, it will be easier for everyone to focus on project
business value and everyone will be able to contribute to project. After all,
we programmers are not there to put buttons on forms; our task is to solve
customer’s problems.
Steve
McConnell said it best in his book Code Complete :
"Programmers
who remember to consider the business impact of their decisions are worth their
weight in gold."
Project
vision is so easy to create that it may seam to obvious, but what is obvious
know won't be in one year, and what is obvious to project leader may not seam
so obvious to rest of the team. Writing one page document to explain 6
months project to 20 people shouldn't be a problem.
I will be covering other documentation types in next posts.