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
- architecture and code
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]
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
McConnell said it best in his book Code Complete :
who remember to consider the business impact of their decisions are worth their
weight in gold."
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.