Some general suggestions for the AHK documentation
Posted: 18 Jun 2021, 04:16
[Moderator's note: This post was split from the (mostly) unrelated topic Classes in AHK, Basic tutorial. ]
I was struck by the word "Classes" in the title - because society seemed much better informed before the introduction of structured programming.
Teccies used to talk to non-teccies in English.
Having taken a recent interest in AutoHotkey I realise that many teccies still talk to everyone in teccie-speak.
And the comment "Unfortunately in Help file Classes described in very complicated way without examples" rings another bell.
I believe that the apparent success of AHK could could be exceeded a hundredfold if its documentation, tutorials and books were completely different in the following respects:
1. The official documentation was not "Class-bound". It was in English and started from the non-programmer users ' view rather than the teccie view.
2. It focussed on AHK's benefits and how to address them, rather than on its technical structure and how to use it.
3. It made use of basic presentational techniques, such as bullet points, diagrams, and examples! Yes examples.
3. It contained lots of examples which were fully explained.
4. A recognition that the purpose of documentation is to teach those who don't know, rather than those who do.
5. Not least, the following topics - which receive fleeting consideration - were treated in depth.
Accessing web browsers
Use of the clipboard
Loops and the creation of menus
Plus many more, including ...
CLEAR explanations of parameters, their benefits and drawbacks, which are mandatory, their their purpose and examples
A comprehensive description of the structure of the process with a recommended code sequence.
Do's and don'ts what should go where.
The existing descriptions pay lip service to the "Structured Programming Documentation Standards". Rather than being focussed on their noobie audience and telling them what they need to know.
And sentences no longer than 25 words!
I was struck by the word "Classes" in the title - because society seemed much better informed before the introduction of structured programming.
Teccies used to talk to non-teccies in English.
Having taken a recent interest in AutoHotkey I realise that many teccies still talk to everyone in teccie-speak.
And the comment "Unfortunately in Help file Classes described in very complicated way without examples" rings another bell.
I believe that the apparent success of AHK could could be exceeded a hundredfold if its documentation, tutorials and books were completely different in the following respects:
1. The official documentation was not "Class-bound". It was in English and started from the non-programmer users ' view rather than the teccie view.
2. It focussed on AHK's benefits and how to address them, rather than on its technical structure and how to use it.
3. It made use of basic presentational techniques, such as bullet points, diagrams, and examples! Yes examples.
3. It contained lots of examples which were fully explained.
4. A recognition that the purpose of documentation is to teach those who don't know, rather than those who do.
5. Not least, the following topics - which receive fleeting consideration - were treated in depth.
Accessing web browsers
Use of the clipboard
Loops and the creation of menus
Plus many more, including ...
CLEAR explanations of parameters, their benefits and drawbacks, which are mandatory, their their purpose and examples
A comprehensive description of the structure of the process with a recommended code sequence.
Do's and don'ts what should go where.
The existing descriptions pay lip service to the "Structured Programming Documentation Standards". Rather than being focussed on their noobie audience and telling them what they need to know.
And sentences no longer than 25 words!