Models and documentation

Models are everywhere around us and other people often try to convince us to follow them. If we know why we adhere to common rules, we have a better chance to see the effect we are looking for. To regain our control and enhance our understanding of existing models, we must selectively choose the parts to which we'll adhere. I we follow what is already established and believed to be true, we give up the chance to make our own mistakes, adjust and learn along the way.

Schools and universities are often troubled to teach new, working models. If we're careful enough, we might find models that are taught there ten years after their initial appearance. People that accept them with no doubt are affected in two ways: (1) they learn what was before, so (2) they have no time to learn what is now.

I try to follow only models that are immediately useful. Some may have indirect advantages or work only in a particular domain. Once the domain changes, they become useless. Different domains have different requirements, so a model that works for one may not work for another.

Documentation communicates the purpose of a complex project to people unrelated with it, facilitates better understanding of underlying details, assumptions or decisions and serves as a snapshot of a state to which we can come back in the future. Without it we may lose track of what we were thinking before. Best documentations are written in natural language and don't require special domain knowledge to be understood. This makes them easy to understand for the average person. Even if we plan working on a project alone, it still pays to document everything as clear as possible, as we never know how many people will join the project and need more information.

Sometimes, documentation is seen as a way to slow down a project or postpone implementation. If short-term functionality is more important than long-term maintainability, this is probably true. But more often it's not. Complexity is achieved in gradual steps, which need to rest on a solid documentation in order to be extensible. This written specification provides the base on which we build—if it's not stable, our projects might collapse and require a new start. It can be costly to maintain it, but the long-term benefits outweigh the costs.

Documentation facilitates discussion and innovation when a variety of people work together. It should be written in advance of our intentions, otherwise we'll forget to describe fully what we did. A user requirements documentation can serve as a contract between a client and a company.

bit.ly/WH0V83