T
tanix
In the light of what has been already said in different threads,
let us summarize the issue of importance of documentation.
There are at least these types of documentation:
1) Real time documentation in the form of context help
while running some program.
2) User documentation explaining how to use some program
or system and what are its parameters and operations.
3) System documentation that describes the system mechanics
to those, who have a clue of its workings.
Probably the most important type of documentation
is the F1 help, the real time context help, proided by
either clicking on some GUI element and hitting F1 key
or as a help button on some dialog box.
You can not assume that someone who is running your program
knows it in and out. Your program is not that only thing
in his life. He might have tens of programs running
simultaneously.
Each program is its own world with thousands if not millions
of all sorts of parameters, functions and you name it.
Every time you switch a tab on your OS main bar, you are
effectlevly switching to a totally different world view.
Most of modern programs of any complexity include tens
of dialogs with tens of parameters.
You can not assume that some funky name you have given
to some checkbox, button, listbox choice or what have you,
is something that user can even comprehend. Quite often,
your text contains all sorts of buzzwords and the user
may not even know what do you mean by things like:
"Allow transfers to occur over existing browse session"
or
"Send REST command prior to APPE when resuming a transfer"
or
"Use SIZE or MDTM commands to gather precise details"
What does it all mean?
Do the program writers assume that the only thing in the
world you do is to run THEIR program?
Basically, EVERY USER INTERFACE ELEMENT HAS TO BE COMPLETELY
DESCRIBED EITHER BY CONTEXT HELP VIA H1 KEY OR HELP BUTTON
ON EVERY SINGLE DIALOG BOX, PANEL OR TAB.
Whan I ran YOUR program, do not assume that I remember
thousands of your parameters, quirks, notions and ideas.
You can only assume that I have SOME idea.
I might be using some program that I did not use in YEARS.
Do you mind if I am using it?
Do you assume I have to have a Phd. in using your program?
Do you assume I am a computer wizard?
Do you assume I have an infinite memory and instant
recall of my previous reincarnations?
What do you think your program IS in the scheme of things
in my own life?
Do you think you are some kind of Jesus Christ entity
and whatever you say is a word of God that I have to
recite the first thing when I get up from my bed?
Why don't you put yourself in the proper perspective?
We'll talk about the other types of documentation
some other time. This is enough for now.
--
Programmer's Goldmine collections:
http://preciseinfo.org
Tens of thousands of code examples and expert discussions on
C++, MFC, VC, ATL, STL, templates, Java, Python, Javascript, PHP,
organized by major topics of language, tools, methods, techniques.
let us summarize the issue of importance of documentation.
There are at least these types of documentation:
1) Real time documentation in the form of context help
while running some program.
2) User documentation explaining how to use some program
or system and what are its parameters and operations.
3) System documentation that describes the system mechanics
to those, who have a clue of its workings.
Probably the most important type of documentation
is the F1 help, the real time context help, proided by
either clicking on some GUI element and hitting F1 key
or as a help button on some dialog box.
You can not assume that someone who is running your program
knows it in and out. Your program is not that only thing
in his life. He might have tens of programs running
simultaneously.
Each program is its own world with thousands if not millions
of all sorts of parameters, functions and you name it.
Every time you switch a tab on your OS main bar, you are
effectlevly switching to a totally different world view.
Most of modern programs of any complexity include tens
of dialogs with tens of parameters.
You can not assume that some funky name you have given
to some checkbox, button, listbox choice or what have you,
is something that user can even comprehend. Quite often,
your text contains all sorts of buzzwords and the user
may not even know what do you mean by things like:
"Allow transfers to occur over existing browse session"
or
"Send REST command prior to APPE when resuming a transfer"
or
"Use SIZE or MDTM commands to gather precise details"
What does it all mean?
Do the program writers assume that the only thing in the
world you do is to run THEIR program?
Basically, EVERY USER INTERFACE ELEMENT HAS TO BE COMPLETELY
DESCRIBED EITHER BY CONTEXT HELP VIA H1 KEY OR HELP BUTTON
ON EVERY SINGLE DIALOG BOX, PANEL OR TAB.
Whan I ran YOUR program, do not assume that I remember
thousands of your parameters, quirks, notions and ideas.
You can only assume that I have SOME idea.
I might be using some program that I did not use in YEARS.
Do you mind if I am using it?
Do you assume I have to have a Phd. in using your program?
Do you assume I am a computer wizard?
Do you assume I have an infinite memory and instant
recall of my previous reincarnations?
What do you think your program IS in the scheme of things
in my own life?
Do you think you are some kind of Jesus Christ entity
and whatever you say is a word of God that I have to
recite the first thing when I get up from my bed?
Why don't you put yourself in the proper perspective?
We'll talk about the other types of documentation
some other time. This is enough for now.
--
Programmer's Goldmine collections:
http://preciseinfo.org
Tens of thousands of code examples and expert discussions on
C++, MFC, VC, ATL, STL, templates, Java, Python, Javascript, PHP,
organized by major topics of language, tools, methods, techniques.