ďWe, as software developers, live in a semi-literate societyĒ
Not unlike most societies prior to the last century.
Most of the critical project, domain, design, and implementation knowledge is kept in peopleís heads.
We donít sufficiently document what we learn and what we do.
Even if we did, others wouldnít have time to read what we write.
If you donít actually hear something, you donít know about it.
If you arenít physically there, you canít possibly know about most things.
You need to pay attention to what floats around.
Encourage an oral tradition
Do all you can to create artifacts that will help others grasp the issues, learn the decisions, and be aware.
Allow time for non-oral means of learning and communications.
Interesting observations. I wonder how much we can attribute this situation to the state of documentation generally in our business?
Simple things like:
1) New products/sub-systems are initially delivered introducing lots of new terminology without reasonable definitions or comprehensive documentation;
2) What documentation that is supplied is dependent on keywords to be located. This demands a certain commonality in the use of (descriptive) words as well as patience while an individual tries out various possibilities. And if the author uses none of those (attempted) words the searcher remains ignorant.
3) The use of simple examples to substitute for description. Most examples use only limited cases of the operands/clauses available. Even when all operands/clauses are shown in examples, they are each done alone and never in possible combinations. Examples also simply tend to show only the 'output' of the example, without explanation.
4) Documentation is more and more dependent on internal links, often to the point where any page is a descriptive line followed by a dozen or more lines of links. It is as if the author benefits of links always supercede the user benefit of links.
I know that not only do I hate forced extra mousing, but even worse I usually 'forget' where I left to get to where I am now so I don't go back as far as needed or I go back too far. The latter is mainly frustration but the former happens a lot too and results in my unknowingly skipping important stuff (and sometimes huge sections).
Factors like these may severely limit the degree of expertise attainable by the average individual unless a very significant level of time for reading/trial/analysis/conclusion is applied by a person. And eventually even the most patient tire of this (unnecessarily) enforced activity.
These factors also tend to keep design objectives hidden, which may be very handy for the product's authors but prevents best-use of the product.
See also: Continuous Obsolescence, which tends to make things worse.
Contributors: Steven Black
Category Software Communities
( Topic last updated: 2002.10.19 08:46:14 AM )