Documentation & Books

[Wolfgang M.Bereuter]

On 07.07.2004, at 01:48, Marian Petrides wrote:

Marian, judy, list

Marian, i agree with a lot you have said before. But..

IMHO the big point why these discussion, arises again and again since 
years on the list, like the good old Nessie. (maybe I should better 
give up talking about this left/right brain - concerns here in the 
scripters world, but anyway, i give it another try;)

> And, one more suggestion:  to accommodate the real newbie programmers,

Forget the "newbie" "programmers". Get the newbies to programming.
Sounds equal, but isnt, why?
If you are a "newbie (rev) programmer" then you are a programmer, which 
is mostly coming from another "programming" tool. That means a left 
brain-talented person, which is interested in programming and has 
learned to think like programmers: digital step by step, word by word, 
tone by tone details etc...) . For him its very easy to understand the 
structure of a script, because it s language-like: word by word / 
variable by variable word by variable, etc... He loves to think in that 
way. Hence he will likely go page by page through a left brain 
tutorial, Documentation etc, because he understands whats written in 
these documentation.

The other one: newbie to prorgramming. Can be a left talented person 
but mostly will not be, because he is not interested in programming. 
until this first contact with a programming tool. Therefore most of 
them are rightbrain talented person. They like association, Colors, 
emotions, creativity. But they hate step by step-things. The do not 
think like a programmer, they have a lot of problems understand whats 
written in the docs. They need a kind of visual instruction.
Judy!
They need, first of all an OVERVIEW of all this incomprehensible 
written details. They are looking for fast capture of the content - 
with one view. The most important thing for a right brainer is to know 
the content BEFORE he starts learning. Therefore they need an Index, to 
get this overview. If they dont get it and must learn from the 
documentation, they will be frustrated immediately. But we all have 
learned very early in our childhood: Avoid frustrations! If they cant 
avoid it or escape of all that frustrations, they will learn to hate 
rev. (As I have learned, hence I know what I m talking about), Because 
I m NOT a natural leftbrained programmer.

If you are interested in getting the big potential of creativity of the 
right brainers, they are about 50% of the  mankind, but I belive less 
than 5% of the programmers, then you have to give them a 
brainfriendly(!) documentation. to have them as satisfied members on 
board. BTW most of them are not(!) already captured, like 90% of the 
leftbrainer, by Visual-(anything) and anyhting.NET.

Apple got this brainfreindly thing with first Mac OS 6.x, and than with 
HC. An some HC Dokumentation have been instinctivly written 
brainfriendly too. That was the great succes of HC in the market of 
(more rightbrain) Mac Users but newbies to programming. An great 
brainfriendly authoring tool, not from Apple, was mtropolis.

If you have a lot of doubts about this brain matters, which are not 
from me, thats common knowledge in the brain science, maybee you 
believe more in the University of Cambridge:

Aoccdrnig to a rscheearch at Cmabrigde Uinervtisy, it deosn't mttaer in 
waht
oredr the ltteers in a wrod are, the olny iprmoetnt tihng is taht the 
frist and
lsat ltteer be at the rghit pclae.

The rset can be a total mses and you can sitll raed it wouthit porbelm. 
Tihs is
bcuseae the huamn mnid deos not raed ervey lteter by istlef, but the 
wrod as a
wlohe.
Amzanig huh?

this works in nearly all languages (aslo acuh in desucth) and gives you 
an idea how our brain is woking and why a fast overview, indices and 
keywords are so important for the understanding, and understanding for 
applying.

Because of another project i have not much time at the moment, but if a 
lot of people are realy interested how my idea of a brainfriendly 
documentation could look like, I can do a small simple example.
my 2 cents

regards
Wolfgang M. Bereuter

Trainingsmaps© -- that´s Speedlearning with Mindmaps©!
INTERNETTRAINER Wolfgang M. Bereuter
Edelhofg. 17/11, A-1180 Wien, Austria
...............................
http://www.internettrainer.com
wmb at internettrainer.com
...............................
Tel: ++43/1/ 961 0418 Fax: ++43/1/ 479 2539