"DIAMOND JEFF" <[EMAIL PROTECTED]> wrote
(regarding 'hidden' facts in documentation)
> But at the same time, it's very hard for someone who
> knows a system to have any chance of seeing it as someone
> who doesn't. And just because something is documented
> somewhere doesn't mean it's easy to find or remember.
>
Agreed. The problem I hit frequently with the MSDN (but
less with the Palm docs?) is that a successful word search
depends on you using the same word as the author. Microsoft
seem to do more language creation than other companies so
you've often got to wade around for a while before you stumble
onto the MS term for the concept and can then search more
rigorously (only to find that the term fell out of favour soon
after creation).
In writing documentation I've often tried to get around this and
the only answer I can see is a glossary. Unfortunately by the
time development gets to the point of writing the glossary all
of the terms are so familiar to the developers that putting them
in a glossary seems absurd. I've found that new recruits to the
development team are a significant resource here. Give them a
notebook and get them to write down any word that didn't make
sense the first time they heard it and at the end of the first week
you've probably got your glossary. Then you have to describe
each of those terms in as many different ways as possible and
you're on the way to a 'gateway' to the language your project
uses.
Pity no-one's ever got the budget to implement this sort of
detail. The first IDE I see that includes tools to do this as a
part of it's standard installation will get my vote.
Chris Tutty
--
For information on using the Palm Developer Forums, or to unsubscribe, please see
http://www.palmos.com/dev/tech/support/forums/
