Let’s start with a definition. The one on The Linux Information Project mostly resembles what I’ve encountered the most times in my career:
Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance and use.
Very general and correct, but is it useful? Let’s see. When tasked with documentation development, we (the professionals) try to prepare well. It’s good to start by defining purpose of demanded documentation. (I’m intentionally omitting now doubts, if any additional documentation is even necessary). By analyzing what exactly we are tasked to do, we quickly find that we should specify both, the recipients (is it for our company, or outside team?) and the language in selected medium (how technical are they?). Architects know how immediate decisions shape future of the project, therefore before any documentation is created, it’s good to consider longevity of upcoming work. This gets us back to medium selection, because every medium is accompanied by appropriate tools, but not every tool is future-proof.
It probably doesn’t end there, yet we already greatly exceeded content of definition. The problem is, a single word – documentation – can be only an invitation to a real analysis. Then, the short and general definitions are cool when we need a slogan (fitting a few lines of easy to remember text), not when we seek technical details.
Maybe sometimes there is an assumption that everyone in the room learned and remember unspoken nuances. Even if they do, it’s still better to be explicit. Some of you maybe recall students at school: they sit silently when professor asks if everything is clear, but actually their smiles are fake, while they are scared to ask for clarification, afraid to sound silly.