There is one thought I have been carrying around for while and wanted to share. Read this if you are interested in how much documentation a software development project really needs. I am not religiously demanding it nor am I denying the need for documentation. There is a third answer…
This article will develop some guideline around how much documentation a software development project needs. The right balance is hard to find. Better, I will try to define how you can find the right balance between documenting enough and documenting too much.
It is important to keep in mind that documentation is no substitute for communication. Communication is one of the most important means of making projects successful. Much more so than documentation.
Would I be pressed for the answer I posed in the title I would probably say: “Just barely enough!”. Documentation in a software development project often creates heated debates. Doing-oriented people want to have less. Quality oriented people often want to have more. It is difficult to judge where the line between a reasonable amount of documentation and overkill is.
A list of perceived (and exaggerated) pros and cons we hear every now and then…
Some of us who religiously feel that documentation is important might say:
- Documentation is a fact. It is required by our methodology. Every project needs to create 127 documents. With those names and this content.
- Documentation ensures that we are doing the right thing.
- We can send those documents to our clients and team members and communicate our ideas.
Some of us feel it keeps us from the real important work and might say:
- Not documenting anything makes us more flexible
- Not documenting anything makes us faster
- Let’s get an intern and let him/her do it
- We do not have enough time
With this exaggerated list of bullet points I wanted to demonstrate that a discussion of this kind misses the main point. Refocusing the question on a different aspect will help us defining the answer we are looking for in a much better way at the same time make everyone feel comfortable. Those who want/need documentation and those who fear the overhead.
3. Rather than asking why, we should ask ourselves what needs to be documented
Personally, I think documentation is an absolute necessity in development projects. The important question – however – is not: “How much documentation do we need?” But: “What do we need to document?”
It is important to capture the primary concepts and decisions. It is important to think about every aspect of the system from an end-to-end perspective to be able to make sure that:
- you – the architect or designer – will be certain that it works, and
- that your client and/or stakeholder will be able to follow your concepts and decisions, be able to review and be able to agree to it.
Capture those aspects of a system that are important to understand how your architecture and design cover the functional and non-functional requirements and – if you have such – which ones are not covered and why. Keep reminding yourself to document the right thing(s), rather than all things in meticulous detail. This means:
- Document those aspects of a system that need elaboration. Do not try to spend too much energy on those aspects that are clear for your client and you anyway.
- Try to get the message across and write them for a particular skill level. It is not to write design documents in the style of a tutorial.
- Stay brief and to the point with what you write. Document to a necessary depth, but not more.
- Stay focused on the facts and decisions of what you want to carry across. There is no need to elaborate on optional behavior.
- Make sure you convey your train of thought and chain of decisions if it is non-obvious.
4. Keep in mind: Documentation is not and is no substitute for communication
Keep in mind that documentation is no replacement for communication. The best way to convey a concept is to do it interactively: draw, show, and explain.
Documentation is the supplementary material for that process. The primary source of information should be you: the creator of the concept. No matter what your role is: architect, designer, business analyst, project manager or something else.
From my perspective documentation is an important vehicle to capture concepts, patterns, and agreed decisions.
It is an important means of conveying concepts and ideas remains personal involvement by communicating and explaining. This way you will be able to keep your system alive and bring everyone on board.
Create enough to be able to convey the concepts. Assume that your reader knows about how technologies are used and focus on what is being done. Keep in mind that the primary reasons for doing documentation are to:
- Capture and communicate concepts and decisions
- Guidance for those times when none of the individuals who developed the original system are around anymore.
- Guidance for newcomers to the team
Remember that communication is of essence. Without communication everything relies on the fact that documentation is also read. And my personal experience tells me that documentation is seldom read. No matter how little amount there exists of it.
[Pic2010] Pichler, M. 2010, “On documenting Software Architecture (for Business Applications)”, A Practical Guide to Software Architecture [online] available at https://applicationarchitecture.wordpress.com/
Copyright © 2010 Michael Pichler