Techincal documentation your best friend or a waste of time?
Everyone is talking about the specifications, design documents, UML, requirements etc. In almost every company you can find some sort of the process. At any job interview you will be asked about your understanding of the software development process and the documentation. Some companies are proud of having very advanced processes, some are proud of not having them. Sometimes the lack of the development process is the process too.
I was never a big fan of Rational Unified Process and similar methods. I am a software engineer and I like the documentation that is specific enough to explain the problem and the solution and that is short. I strongly believe that for any task and any team there is certain amount of project documentation that is just right. Too little and the people do something different from what they were supposed to do (or they do not do anything at all if they lack imagination ;) ). Too much and the team wastes its time reading something useless (best case) or the people get stuck reading the contradictive statements and trying to find the truth.
Why it is bad not to have enough documentation?
Strangely, this question is still being asked by the software engineers. Sometimes they honestly do not understand why. If they work on their own almost-standalone module or tool and everything is clear - why bother? They are good enough to understand the whole thing without having to document it.
The documentation is the way to communicate the ideas between different organizations
With all respect to the business guys, they speak different language dialect. Engineers do not always understand them and they do not always understand the engineers. So, the only way for them to say something clearly is to write it on the paper. With the pictures, preferably. And the only way for the engineers to make sure they get it right is to ask the questions in writing, referring to the document. And the only way to make sure the engineers have got it right (or wrong ;) ) is to provide the written feedback. And so on…
Functional specifications is the official translation of not-very-technical requirement documents into the engineering dialect of English (French, Chinese etc)
Engineers should not deal directly with the requirements, otherwise there is a risk that their interpretation of the requirements may be incorrect or may not fit to the product. There must be always somebody who takes time to translate the high-level requirements into the specification. Consider this example:
- Requirement document says:
- The system allows the user to calculate the sum of two numbers
- Functional specification says:
- The user opens the "Add numbers" dialog by using the "...." menu item. The UI mockup of the dialog is shown on the Figure 123. The dialog consists of: two input fields "Number 1" and "Number 2",the read-only field labeled "Sum" and two buttons: "Calculate sum" and "Cancel" The system allows the user to enter "-" character at the beginning of each input field, after than only digits 0-9 and the decimal delimiter (subject to the default locale configuration) are allowed. Only one decimal delimiter is allowed per field. When the user clicks "Calculate sum" the sum gets displayed in the "Sum" field. If one or both fields are blank the error message "You have to enter two numbers" gets displayed as modal dialog. Clicking "Cancel" button dismisses the dialog.
How many different layouts you can imagine if you just read the requirements? How many different error scenarios? Do we support negative numbers? Etc, etc. Yes, the functional spec may be much more verbose than the requirement document. However, look how easy it is for the developer to implement the feature now. And how easy is for QA to validate that the resulting product does exactly what it was supposed to do. And, actually, even before everything is in the code, how easy it is for everyone to look at the specification and find errors/missing features or potential problems.
What does it take to write a good specification? Good overall knowledge of the product, enough experience in the domain, good language skills and, most importantly, the will to make everything clear enough for everyone.
Documentation is the best way to validate your ideas
You need to implement a great Web service that provides access to the database. You open your favorite IDE and in a couple of days it is done. What? The DBA guy is angry at you because you do not properly set the transaction attributes and break the data integrity? The deployment guys have spent the entire evening trying to figure out why the application has suddenly stopped responding? It has turned out that the clients open so many connections to your service so the server chokes.
Specification is the only "legal" document that you may use to defend yourself
In any team and any project the conflicts happen. The caller passes the integer and the string and the service expects two strings - who is right? The correct answer is - the documentation. If there is no documentation - both are wrong. Probably there should have been two integers ;) Once everyone agrees on the specification, this becomes the by-law for the team. Yes, the law may be stupid - but then it becomes everyone's problem and it gets solved by the entire team at meeting. No finger-pointing.
Specification is the best way to communicate your ideas and to describe your solution
A well-written 2 or 3-page document (even attached to your issue control system) can save you from many hours of useless discussions, stupid questions and integration nightmare. If there is a problem or an improvement that affects multiple modules and several people are involved in the the resolution, it would be much better if someone takes some time to write a short action plan. It does not have to be collective effort at the beginning, we are not talking about a change that takes hundreds or thousands of human-hours (in this case it is a big job and has to be carried out appropriately). Once the action plan is complete, it gets either sent to the team or just attached to the issue control system. Then all the people involved are expected to speak up or agree. If everyone agrees with the plan once the work gets done by everyone you will see the magic - the integration will take no time.
Documentation provides the protection against a disaster
The team members may leave at any moment, voluntary or not. One of the engineers may be hit by a bus and (putting aside the personal feelings) you do not want his knowledge of the system to be lost. At least minimal amount of documentation concerning the work of everyone in the team is your warranty against failing to deliver your work on time.
When the documentation becomes useless?
Unfortunately, in certain situations or environments the documentation may become useless or even do some damage, slow down the project development, lead to the integration nightmare and unhappy QA filing tons of bugs that do not make sense to the engineers.
The expression "the more the better" does not apply to the documentation. At least after certain threshold. If there is too much documentation for everyone, the people do not read it. If the people do not read it, first of all it is a waste of time to write and maintain this documentation. Secondly, it does not serve its purpose. The more documentation you have, the more difficult is to maintain it (and the dependency is not linear!). And the outdated documentation that has lost its connections with the real system may be worse than the lack of the documentation.
Obviously, the team has to be given enough time to work on the documentation. This includes everything: writing, discussing, collecting feedback, reviewing, approving the specifications. If this time does not get allocated and planned as it is supposed to be, the documentation is guaranteed not to be good enough or it will be written after the implementation is complete.
It is important that the people who write the documentation understand why are they doing it. If they do not, then the results will be unexpected. After reading the hundreds of pages of the functional specifications the people will still ask the important questions about the system. The engineers will complain that the assumptions used in the documentation are wrong and the system does not function (even now) as it is described. The public documentation reviews won't help in this case. Right questions will not be asked (because there is nothing to refer to) and, thus, will not be answered. And usually no one will have enough courage to say that the whole document is unacceptable.
Sometimes the people (especially if they are dedicated designers/architects etc) become too obsessed with their job. It may result in a scientific paper with the expressions of at least 50 words that are generally correct but…require interpretation. And, as you imagine, different people interpret them differently. However, the computer science is still about the exact answers. Complicated and unreadable documentation usually passes the review phases relatively easy (again, sometimes the people hesitate to admit that they do not understand it). As long as the preface sounds good, the primary stake-holders accept it too. Result? A lot of confusion, the same question being asked over and over again, the system that does not always do what was expected and the way it has been planned. And QA cannot validate the system behavior since they do not know how it is supposed to work. They file the bugs that do not make sense to others and the whole process slows down.
Real-life example
One day my former boss asked me to write a set of design documentation for our application (we did not have any). I was shocked - he never bothered about this useless stuff. Later I have learned that he was publicly accused by the boss of another team about the lack of the process and design documentation so he has decided to fix it. As usually, in a timely fashion (i.e. ASAP with the deadline expired last Christmas). Needless to say that this job has not been completed, after spending a couple of days and producing about 30 pages of text, diagrams etc I was interrupted with another "fire" alarm. However, it has been reported that now we do have the design documentation ;)
Conclusion
No doubts, the project documentation is very important in software engineering. But, like everything else, it has to be balanced with other key components like time, people, tools, environment, process etc, like the components of a good recipe if you want to enjoy the food you cook. It has to be written by the professionals with the broad knowledge of the system if it is about a major part of the system or it can be written by any team member if acceptable. The team members should be encouraged to document their work, share their ideas and actively participate in the team documentation efforts.
blog comments powered by Disqus