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.

Amount of written requirements

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

"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.

In my previous blog post I've said something about the reasons of documenting software. Now the question is how to do it? People don't like to write documentation, documentation is often hard to find and maintain and it is usually obsolete. We need to organize documentation in such way that it is meaningful, easy to maintain, easy to find and hard to become obsolete. You can say that right solution is somewhere between full bureaucracy and anarchy.

Process oriented solution

Some people believe that with detailed organization and business processes they can completely controls their business. This approach is something like programming humans that are executed by business process. In this environment programmer would have to follow exact documenting process and typically fill big documentation templates with concrete information. This procedure can guarantee that people will avoid documenting at all costs and it doesn't guarantee that information populated in templates will be useful enough. It may give away false impression of fully controlling this vital activity but in practice it isn't so.

Programmers dislike (hate) writing software documentation because it is not interesting and creative. If they are further more crippled by heavy formal process, programmers will do what ever they can just to finish that part of work by filling templates with low quality and incomplete information.

If it is not easy for programmer to find and update some information he simply won’t do it (if he is not explicitly asked to do it). As software evolves and knowledge of the real system increases, documentation becomes obsolete because programmers are not updating it. After enough time has passed you are faced with massive obsolete documentation that in the end of the day is making more harm than good because you can never know if information is accurate.

People oriented solution

My opinion is that company Wiki site (e.g. ScrewTurn Wiki ) is much better solution for knowledge base than bunch of populated word templates resting on some server's file system. Pages on Wiki site are easier to search, easier to alter and they can automatically notify all participants when documentation changes. This approach can seam frightening to management because everyone can alter any document they want. In general, employees shouldn't be constrained in their work so that they can not make mistake. Not being able to make mistake means that you aren't doing any creative work and that you should be replaced with machine. Instead, company should introduce quality checks for activities that are more likely to introduce an error or where error can be very expensive. Some dedicated person (e.g. project leader) could inspect all documentation incremental changes in previous weak and verify them. Bear in mind that almost all Wikis will automatically store document versions and track changes. This way person who made mistake can always easily be identified and document can easily be rolled back to previous version.

After you created infrastructure for easy and fast document manipulation you still need to create firm climate (culture) to motivate people to contribute to knowledge base. This is the only way that firm knowledge will grow and knowledge will be effectively passed between coworkers. After all, what are knowledge workers without good knowledge base?

In my next post I will write about what should be documented and how, so if you are interested hook up to my blog feed and stay tuned.
What are your experiences with writing software documentation? 

First theme I will write about in this blog is software documentation. It feels like natural starting point or at least it should be. Documentation must exist in some shape and volume before you start with development. Documentation purpose is to capture knowledge, keep it from misconception and forgetting. It is important for all participants in software development life cycle, from customer, through PM, developers, tester to users. All of this sounds logical, we have all been taught these things.... so what's the problem?

The Problem

Problem with documentation is that its creation can be boring and documentation can easily become out of date and useless. Documentation also takes lot of time, which is taken from development.  After all, you can not compile and run your documentation. Because of this, people can easily forget importance of documenting one highly complex system, where misunderstanding is happening on every day basis, and will easily drop it in background when time becomes critical factor... and time is often critical. At the end of the day/deadline, if needed functionalities don't exist, existence of documentation is irrelevant. It is interesting that writing documentation is not problem only to developers urging for freedom and creativity, it is also problem to customer. Customer would usually say that of course he wants his software documented, but at the end of the day he usually want be willing to participate in its creation, updating and clarification. 

The Need

Now that I covered some of the problems with documentation there is a question "Why should we bother with writing documentation?”. One of the main attributes of software is complexity. Software is usually built to automate some business processes and handle some system complexity transparently. We can say that there are several complexities in software development:

1. Domain Complexity - natural complexity of domain for which software is made.
2. Application Complexity - complexity of application design. This is artificial complexity that can be added for greater reusability, maintainability or can be added by accident.
3. Technology Complexity - complexity of tools and technology used for development.

So we already have three sorts of complexity. That is a lot and only one of those can be pretty large. You should also note that domain can be fairly unknown to customer him self. He could also fail to explain domain to developers, or developers can misunderstand him.

Application complexity can be pretty complex as initial design on paper, with no coding. As system grows, requirements are changing, code is changing, as time runs out developers are hacking their way through code... In worst case, application complexity can reach so high level that no changes are possible and project is dropped.
As for technology complexity, we all know that technology is changing which doesn't mean it is advancing.

From all above we can conclude two things:

1. Software development is hard.
2. Software documentation is very much needed.

In next post I will be covering some advices on writing documentation so hook up to blog feed.