Vukoje's blog about software development

What should we document?

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:

  1. project vision
  2. requirements
  3. 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.