Some general suggestions for the AHK documentation

[SolihullRog]

[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!

[Chunjee]

I'm interested in writing this up. But I would need at least five-ten sponsors because its going to take a number of hours.


interest check?


classes force more structure into the code; ahk being very unstructured, I think it helps organize generally.

[swagfag]

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.

• what even is "Class-bound" and how is it "Class-bound"? sounds like something u made up on the spot
• it is in English
• theres the quick tutorial for that. rather what you need to recognize is the fact that this is AutoHotkey's documentation, and not a Teach Yourself Programming in 10 Easy Steps 101 guide. its primary purpose is documenting ahk features

2. It focussed on AHK's benefits and how to address them, rather than on its technical structure and how to use it.

if u know how to use something, u can infer what it could be good for. thats not the case the other way around

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.

more examples is nice, but the more u have of them, the more ull have to maintain. granted this isnt as big an issue for v1 and probably isnt going to be as big an issue once v2 fully releases, but still.
diagrams are even harder to maintain(unless u pull in a dependency like plantuml or graphviz, but then u have to deal with having that dependency)

4. A recognition that the purpose of documentation is to teach those who don't know, rather than those who do.

yeah, it already does that. also see previous points

5. Not least, the following topics - which receive fleeting consideration - were treated in depth.

• Accessing web browsers
  see point about maintainability. not only would u have to check the implementation against all ahk supported platforms, when Microsoft or Google break an API, ull be now forced to update the ahk docs due to something not related to ahk itself.
• Use of the clipboard
  what about the current docs is it that u find lacking? if u need to do something more complex than reassigning, ull have to also be aware of the windows specific clipboard concept - and for that there's the windows docs(MSDN).
  no need to regurgitate the content in the ahk docs(which would mean ud also now be responsible for maintaining it should anything change, yuck).
  i guess it could link to more advanced stuff on MSDN, in case people didnt know where to look for it
• Loops and the creation of menus
  seems awfully specific, but whatever, ok
• CLEAR explanations of parameters, their benefits and drawbacks, which are mandatory, their their purpose and examples
  what is unclear about the way theyre explained currently? suggest concrete improvements
• A comprehensive description of the structure of the process with a recommended code sequence.
  there isnt one. ahk is a multiparadigm language. u can write procedural code, u can write imperative code, u can write in functional style. none of these concepts though strictly relate to ahk, so why go over them in the ahk docs?
• Do's and don'ts what should go where.
  the Don'ts are already described, see Deprecated. everything else is fair game
• 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.
  at this point im detatched. what is it specifically that u think they need to know? please dont say "a primer on programming"
• And sentences no longer than 25 words!
  lol seems kinda arbitrary. a sentence should be exactly as long as it needs to be and no longer than that.
  spend any significant time going through the docs and ull soon enough realize that, at least for the pages he wrote/edits himself, Lexikos goes to great pains to describe everything as fully and succinctly as possible.
  There are no wasted words, there is no fluff. if something mentions something, there was an explicit reason for doing that