Never Explain

As a general philosophy, you should never explain. This is not a matter of being selfish, per se. It is more that true knowledge comes from both loving the people that you set as examples, and as always, the BestLearningIsByDoing.

The problem with explaining is really that, not only is it a waste of time, but in actuality you may be doing the recipient of your explanation a disservice. They are asking for an explanation, after all, because they can't figure out what you know by themselves. They are looking for a shortcut to knowledge. But there are no shortcuts to knowledge. We LearnFromExperience.

Another aphorism that pops to mind is ElbertHubbard?'s "Never explain - your friends don't need it and your enemies won't believe you anyway."

So how does this apply to design? I am not ForsakingDocumentation?. Rather, explain in a method that is appropriate to the future developers and clients of your system (definitely yourself inclusive). Document and describe from the perspective of providing insight to somebody with a specific need, rather than as an explanation as to why things work the way they do, or why you followed a specific methodology or algorithm.

This philosophy has at least two problems:

it excludes those of lesser talent from working on a project
it makes the use of incomprehensible jargon both permissible and impossible to deal with

Hmmm. I must disagree. The point is not "prevent explanation from being attained" but rather to ensure that knowledge is directly acquired, without filters. As to the two points:

A certain level of talent is required. Your documentation must assume a threshold. Below that threshold, you don't want such "talent" working on the system.
Jargon is something you ALWAYS document. Exclusionary "insider speak" is common enough in any field, but you must have a glossary or lexicon for it. If it's jargon from an engineering standard, then a copy of the standard must be on hand. If it's home-grown (locally generated) jargon, then a home-grown glossary/lexicon is maintained.

You keep SourceMaterial available, and you always ReferToSource?, rather than "explaining" -- which is, of course your understanding of the source. Establish a standard or acquire the standard and use that as source. If you need to explain, then either the standard/source is broken (so fix it) or the "talent" isn't up to the task (so fix that).

I think, that to explain should be considered more broadly. You can explain something, by giving helpful examples, that can be worked out by the questioner. Or explaining the words you use by giving definitions for them. But not explaining the consequences or reasons for the definition.

This page just bubbled up from your hidden childhood memories "I should like to make one thing perfectly clear: I never explain anything." ... remember... it was Mary Poppins. ;o) --AndrewCates

Sometimes you paraphrase your understanding of the system to someone. Then that person passes it on to the next person ... each person paraphrasing their understanding of the system, with some loss at each step.

Much better for the original programmer to document the system with on-line help, so that as long as the message "See that "Help" button ? click it" gets passed along, the last person gets *all* of the information that the first person got.

If a programmer *needs* to explain something to a test user, then the user interface is broken or the on-line help is incomplete.

Ideally, everything would be intuitively obvious from the user interface, and very little on-line help (and no verbal help) would be necessary.

The article on the CabalDesignProcess mentions programmers watching as play-testers try to run the program. The programmers are specifically forbidden to say *anything*.

The best teachers get their students to explain the solution to a problem to them.