A case against the almighty project document
To create good documentation is an art for itself and most often underestimated by us fellow software developers, architects and software project management folks. I won’t go into the detail of what makes a good documentation (in my point of view) in this blog post too deeply (maybe in the future, if you are interested?). Instead I want to point out a negative point which I run into quite frequently: The almighty project document.
Andreas Rüping suggests in his book Agile documentation to create small and highly focused documents, targeted at:
- An explicit target audience (This dictates for example the kind of information and the tongue the document is written in)
- Readers interested in a special part of the project/information (This dictates the contents and structure of the document)
These documents are laid out in a document landscape. The landscape is formed by different types of documents (for example: Requirements specification, conceptual description, business goals, architecture overview, API description, etc.). The landscape is developed over time by creating template and example documents. If you start a specific project you simply pick the matching documents and fill them with contents. The maintenance of the landscape can be a project in itself or you can just develop it while you are working. The result is a (more or less) coherent set of documents across multiple projects which are short (easily digestible), focused and easy to navigate. You will become more and more familiar with the types of document over time and find the relevant information more quickly.
The Antagonist of this type of documentation is the almighty project document. It is a chimera born out of all different kinds of project documents and information. Most of the time it’s this kind of document which is shown to clients who really care about documentation. Often supported with sentences like “Look, we produced over 200 pages of documentation”. If you take a closer look at the document you will most often notice that the contents consists of:
- A (too) general introduction to the topic of the project
- A definition of goals
- Copy and pasted examples from the manuals of the libraries used in the project
- Duplicated reference manual sections of the libraries used in the project
- The complete source code/config files (of course not in sync with the VCS any more)
- No really clear statements of what should be done/has been done
- Information from different time frames (planning/implementation/review)
- …
This information is often not structured in a very good way and delivered in a PDF without a navigateable table of contents (so that page numbers in the ToC differ from the real page numbers) or hyperlinks. The fellow developers or administrators who have to work with the documentation will only get half of the needed information out of the it and will waste time checking back with the management folks. The resulting product will most certainly miss some important aspects and if you have to look back at the project you will surely be confused.
Additionally this document violates an important principle of concurrent access to a resource (speaking: teamwork): Keep the chunks which need to be accessed by multiple persons at the same time (programs) as small as possible. In a web project you often separate the program into a set of files defining the output (templates, view files, you name it) and a set of libraries/scripts/whatever. This is not only to keep the webdesigners from having to read the program code but also to allow the presentation and the program to be edited at the same time. Do yourself a favour and not only spend time designing your software, also design your project documentation.
One last word: Of course I consider myself guilty of having produced some kind of an almighty project document (although maybe not as evil as described above) from time to time. You simply can’t do everything right in a constrained environment like the real world. But the more often we stress the importance of good documentation and information design we will maybe come to a point where good documentation is considered really valuable and therefore honoured and budgeted with time,dedication and respect.
Do you have your own thoughts documentation? Ever or never produced a real beast? Please comment.
Dilbert on documented processes
Tags: Development, Documentation, Opinionated, Project-Management, Software