Because folks treat documentation as a "checkoff" item: Have documentation? YES NO
Many people/organizations don't produce formal specifications, test plans, test results, etc. They just have some "random" collection of paper that they can point at when asked about "documentation"... and, no one has much interest in checking to see if any of it is correct or USEFUL!
I have long adopted the approach of writing a User's Manual before beginning a design. It forms an informal specification -- in terms that a user can understand (instead of "stuffy tech-speak"). And, it helps me think about a *unified* approach to a design -- rather than letting the design "evolve" (which seems to be the design methodology du jour!) in unconstrained directions.
When that is done, a customer/client *knows* what the end product will be like and can critique each design decision that the document presents "as fact". It lets hypothetical users ask, "How do I..." and "What if..." questions -- all of which SHOULD be covered in the document.
At that point, the actual *implementation* is a piece of cake! All of the decisions have already been made -- no fear of coming up with two DIFFERENT approaches to two *similar* problems in the user interface because "you got a better idea when working on the second".
Yup. First, they need to be able to stop "delivery" of the product (in order for their efforts to have any "weight"). Second, they need to be "nit-pickers" to ensure they have the requisite skills to *catch* ALL discrepancies.
I'm "too small" to take on many of the projects that I do undertake. And, too "lazy" (unwilling to put in extra effort that shouldn't be necessary). So, I try to design mechanisms that amplify my efforts; do more by doing less.
Tying the documents to the actual implementation is one such example. The documents and the implementation are always in sync (if you let the makefiles do their thing!). It's also a carrot for future developers (maintainers) as the documents provide a friendlier way of viewing and entering changes to the codebase.
For example, a recent document explains and tabulates the rules by which I convert letters to sounds (part of a TTS). The document organizes the rules in a nice, easy to read format. A piece of code that I wrote extracts the rules from the document, rearranges them to satisfy the optimizations that the run-time implements, then encodes them for inclusion in the actual run-time.
A developer *could* insert himself into the middle of that process if he chose to. I.e., take the encoded output from version X of the ruleset and manually introduce changes to advance it to version Y -- without updating the documentation. But, it's almost certain that he will introduce a bug/typo in the process. And, will have to manually revise the regression suite to cover his changes (another opportunity for errors).
Expecting developers to be "lazy", the *intended* way of modifying the rules -- by altering the documentation -- is so much easier (and robust) that it is unlikely anyone will *try* to circumvent it!
Don't discount the fact that many people are not invested in the process. And, others may not be familiar enough with the technology to be *competent* to recognize a subtle mistake! Or, leary of expressing their uncertainty ("Surely Bob would have commented on this *if* it was a genuine mistake...").
One legacy letter-to-sound algorithm often implemented "wildcards" to represent letter patterns of interest. E.g., "any number of voiced consonants". But, the original implementation language was SNOBOL. Folks recoding the algorithm (into C, most often) would carelessly interpret the implementation as, literally, "any number of voiced consonants". And, naively implement a greedy matching algorithm (common in C):
while (char in {L, J, V, D, ...}) pointer++
This *looks* correct. Until it is applied in particular contexts: %D (where % is the aforementioned wildcard). Obviously, "%D" should match "coLD", "aDDed", etc. I.e., the % matches the first (and ONLY the first) of these voiced consonants and the explicit 'D' matches the immediately following 'D' -- even though it, too, is a voiced consonant.
But, the above implementation will fail -- due to its greed!
This is a common latent bug in implementations of this particular algorithm. Because the folks re-implementing it (in C) failed to understand how the original SNOBOL implementation operated.
Tools like MSWord appeal to folks who think "pretty printing" is a goal. Or, who are tickled with the prospect of embedding a picture or a scope trace in a document.
Lately, my documents have been interactive. E.g., the document I am working on presently allows the user (i.e., reader) to explore how various glottal waveform parameters affect the *sound* of the spoken voice -- by adjusting them and *listening* to the resulting pronunciation of (canned) words.
[You could spend paragraphs trying to explain these sound qualities and never be certain the reader understands; but, give him an actual sound sample to evaluate -- and contrast -- and your confidence in his understanding goes up markedly!]In my case, I opted for Perforce -- much to the chagrin of all who advised me on the subject! A big part of that, IMO, was a desire to operate in their own little isolated fiefdoms, detached from The Organization. And, failing to perceive the needs of others in that organization!
Sorry, change is always painful. :( That's often why folks cling desperately to old ways of doing things and "wetware systems" (in which the "system" has been designed to fit in someone's braincase early on -- and never revised when the constraints of that braincase were exceeded!).
An exec at a Fortune 500 company ($10B/sales) once quizzed me on the design of part numbering systems. I gave the typical reply: "Numbers beginning with 1 for vegetables; 2 for fruits; 3 for meats;
4 for cereals; etc. The next digit could refine this further: 11 for leafy vegetables; 12 for legumes; etc."He took a tomato out of his desk drawer: "Vegetable! 1XXXX" "No, it's a *fruit*!" (how many folks trying to rely on this "wetware" system would make a similar mistake?)
"Hmmm... What about berries? Strawberries, blueberries...?" "... tomatoes, avocados, grapes..." "Huh? Aren't those fruit?"
"And, where do we put *candy*? And vitamins? And..." "All those oddball things can go in the 9's!"
I.e., systems that appear simplistic usually are... too simplistic! The conversation ended with him arranging the items on his desk in a haphazard order and "identifying" them in exaggerated fashion: "1, 2, 3, 4, 5, 6... get the picture?"
"Then, how do you know what a 62347 is?" "I type the part number into this computer and it tells me everything I want to know about it! What it is, what it costs in materials, labor, how many we have on hand, how many we have active orders for, how many we sold last year, what time of year has the greatest demand, where (geographically) that demand is located, etc. To *someone* in this organization, each of those items are THE MOST significant aspect of this product. If *that* person was designing a part numbering system, he would choose to encode *that* data in the part number and care little about the criteria *you* chose!!"
[I can't resist quoting Earl Sinclair: "As you can see, I have separated all known dinosaur wisdom into three categories: animal, vegetable, rocks.""Water is the opposite of fire, which we have previously established as a vegetable. What's the opposite of a vegetable? Fruit. So, water is a fruit! Fruit is not a vegetable, so it has to be either an animal or a rock. We know it's not an animal. Therefore, fruit is a rock."]
Why the need for specific folders/directories for each item type? Sooner or later, you will end up with huge directories and shrinking namespaces. Why not let things live where they "should" live -- just ensure they are accessible from everywhere that they should be accessed?
E.g., if I embed a particular object in a particular document... then, at a later date, decide that the object can also be used in some other document, I don't refactor the original document to extract the object and move it to some "shared" location. I just reference it where it was.
[I am becoming a huge fan of relational databases! Letting objects reside in the DBMS instead of as files in a filesystem. It makes it easier to see dependencies]Your goals are far more ambitious than mine -- I just want to keep my docs synchronized with the objects they describe. I count on the VCS to handle much of that "make" overhead, currently.
You can also opt to not be concerned with "presentation" (depends on where your docs will be consumed). E.g., web pages tend to be content driven; PDFs are layout driven.
Also, consider what you will want *in* those documents. I think (as evidenced from my current efforts) that documents will become much more "active" than "dead tree products". So, you may find that "text's" role decreases over time to other media forms.
Good luck!