[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
eagerahk
Posts: 122
Joined: 02 Dec 2015, 06:27

Re: Suggestions on documentation improvements

19 Sep 2017, 02:43

This suggestion needs to be reconsidered. Thanks!
Last edited by eagerahk on 20 Sep 2017, 21:52, edited 6 times in total.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

19 Sep 2017, 13:49

SoundSet

The doc for Soundset states the first parameter must be a number. Why can it not be OFF or ON?

If "Soundget, outputvar, Master, Mute"" returns ON or OFF, I can't write something like:

Code: Select all

Soundget, masmute, Master, Mute
Soundset, 0, Master, mute
soundplay,   somefile
Soundset, masmute, Master, Mute
User avatar
TheDewd
Posts: 1503
Joined: 19 Dec 2013, 11:16
Location: USA

Re: Suggestions on documentation improvements

29 Sep 2017, 16:02

joefiesta wrote:Soundset, masmute, Master, Mute
You could do this: SoundSet, % (MasMute = "ON" ? 1 : 0), Master, Mute
If the saved variable is equal to "ON", then behave as the number 1, else if the variable is "OFF' then behave as the number 0.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

30 Sep 2017, 05:24

Code: Select all

x := [], handleX := 0x4321, handleY := 0x1234
x.InsertAt(handleX, "A")
MsgBox % x[handleX]  ; A - okay
x.InsertAt(handleY, "B")
MsgBox % x[handleX]  ; Empty
MsgBox % x[handleX+1]  ; This is the new "position" of "B"
Should be

Code: Select all

x := [], handleX := 0x4321, handleY := 0x1234
x.InsertAt(handleX, "A")
MsgBox % x[handleX]  ; A - okay
x.InsertAt(handleY, "B")
MsgBox % x[handleX]  ; Empty
MsgBox % x[handleX+1]  ; This is the new "position" of "A"
Recommends AHK Studio
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

30 Sep 2017, 10:12

Returning to an earlier post on the webpage titles you get when you use a search engine.

Suggestions on documentation improvements - Page 12 - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 69#p150569

When I searched for the Hotkey command in Google, a result appeared but had the webpage title 'AutoHotkey' and not 'Hotkey' which meant I didn't realise it was the right result. Thankfully there don't seem to be any real problems with any other webpage titles, however there are some other mismatches listed below.

Regarding a suggestion in the post after the original post, Google gives the title 'AutoHotkey' not 'Hotkey' when I use these search terms also: "site:autohotkey.com" Hotkey.

I wrote a script that takes an htm file, e.g. docs\commands\Hotkey.htm (obtained by decompiling AutoHotkey.chm), generates a url e.g. https://autohotkey.com/docs/commands/Hotkey.htm, and navigates to a url which is equivalent to pasting it into Google's input field to search for it. The script then retrieves the webpage title of the first result as returned by Google.

So here are the title mismatches (i.e. between the htm file's title retrieved via an HTMLFile object and between the text of the first result of Google. For mismatches I subsequently retrieved the text from Bing and Yahoo! manually.
Spoiler
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
jonathan scott james
Posts: 42
Joined: 05 Apr 2016, 01:56

Re: Suggestions on documentation improvements

10 Oct 2017, 13:39

help should have it's own client
i'm using xp, i cant seem to make the search function of help does not find parts of words
when i type a_tick , it cant find a_tickcount, it acts like it the search param has a space at the end and finds nothing.
Guest
Posts: 57
Joined: 17 Oct 2013, 02:32

Re: Suggestions on documentation improvements

10 Oct 2017, 14:05

jonathan scott james wrote:i'm using xp

1. XP should go the way of the dodo, upgrade to something decent like Windows 7. Don't expect current software to keep working on obsolete systems.
2. There is the online help documentation: https://autohotkey.com/docs/commands/index.htm - you can copy the html here https://github.com/Lexikos/AutoHotkey_L-Docs so you can browse it locally (just open autohotkey.htm)
3. There are alternative CHM viewers like KchmViewer which may work better, portable even (e.g. no install needed) https://www.portablefreeware.com/index.php?id=2744
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

10 Oct 2017, 15:50

Guest wrote:
jonathan scott james wrote:i'm using xp

1. XP should go the way of the dodo, upgrade to something decent like Windows 7. Don't expect current software to keep working on obsolete systems.
2. There is the online help documentation: https://autohotkey.com/docs/commands/index.htm - you can copy the html here https://github.com/Lexikos/AutoHotkey_L-Docs so you can browse it locally (just open autohotkey.htm)
3. There are alternative CHM viewers like KchmViewer which may work better, portable even (e.g. no install needed) https://www.portablefreeware.com/index.php?id=2744
1. We still didn't remove compatability with Windows XP
2. so any kind of software delivered with AuoHotkey should work with any targeted system
3. without the need to install any kind of additional software.
Recommends AHK Studio
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

10 Oct 2017, 17:16

From:
jeeswg's documentation extension tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=33596

[chm to txt]
[C:\Program Files\AutoHotkey\AutoHotkey.chm to a txt file]
htm to txt, AutoHotkey Help (chm file) to txt - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=26402

[chm to separate htm files]
[C:\Program Files\AutoHotkey\AutoHotkey.chm to separate htm files]
E.g. use 7-Zip.

I.e. once you have txt / htm versions of the help file, it's much easier to search for things e.g. use NirSoft SearchMyFiles.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
Stamimail
Posts: 77
Joined: 06 Nov 2014, 08:48

Re: Suggestions on documentation improvements

16 Oct 2017, 15:37

Hi, I just finish reading the "AutoHotkey Beginner Tutorial".
I feel it needs improvement.
1. There is no explanation as to how to proceed from there.
2. I feel that I haven't enough tools/knowledge to make things.
I want to suggest a different approach to how to make it.
My approach is based on the idea that the user needs to feel that he is obtaining useful tools while learning.
So that's how it goes:
There are many useful scripts out there.
You need to find the most useful scripts that are useful to almost every user.
Choose one or two scripts for each chapter. The chapter will focus within the script on the lines related to the subject of the chapter.
The point is, the user learning the chapter, and get a useful script, that encourage him to explore more (desirable in the subject of the chapter) how to customize the script and make it better for his needs.
User avatar
Exaskryz
Posts: 2882
Joined: 17 Oct 2015, 20:28

Re: Suggestions on documentation improvements

16 Oct 2017, 16:39

@Stamimail, I think that's a problem.

What defines a useful script for anyone?

I could teach you how to remap your keyboard so that if you enable CAPS LOCK you τυπε ιν γρεεκ λεττερσ. I could teach you how to make a MsgBox that appears every 5 minutes, or a timer that records when you were last active. But do all people have uses for that? I doubt it.

And the problem is there are so many directions to go. Maybe someone found Autohotkey because they wanted to make playing a game easier -- they'd only be interested in primarily using the Send, Click, and Sleep commands. Alternatively, someone may have come here and wanted to build some kind of interactive record keeper or a digital timer; they'd be interested in the power of a GUI. Maybe someone wants to be able to play sound effects whenever keys are pressed on their keyboard; they'll want to learn about SoundPlay. Maybe someone wants to have a kind of JARVIS which welcomes them when they log on to Windows - that uses ComObjCreate and the SAPI program.

I think it's up to the user to learn how to use the documentation after the tutorial. There are mini-examples at the end of most documentation pages that demonstrate how to use a particular command. The only pitfall I see is being able to identify what command the user needs without knowing anything. That's what coming to the forums is for, but also what using the search feature is for. Even if they end up close to the command they want, there is the Related Commands section that they can explore to find the command they're looking for. Example is SoundBeep vs SoundPlay.

---

There may well be a use for a place like "Script Ideas" for someone who is casually looking for an introductory project to learn the language. But I don't think the documentation is the place for that. The forums are. I personally explore the Ask for Help forums and get inspiration from time to time on something that uses a command I have yet to use, one I haven't used in a long time, or one I have very little familiarity with.

Despite that, I still think people discovering AHK come with a goal in mind. I see it often in the Ask for Help sections where someone wants a script to repeat a key press or moving the mouse or detecting colors on screen. They usually haven't explore the tutorial, and if they have, they didn't know what commands to look up.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

16 Oct 2017, 16:43

I'll be doing a full beginner tutorial in the near future. For the moment, is this any good for you?

[using Notepad to introduce AutoHotkey]
jeeswg's Notepad tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=31764

If you have any key areas you want to know more about, do state them, i.e. it would be most useful if you could state as fully as possible, the kinds of things that you believe you would like to know more about. Cheers.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

16 Oct 2017, 22:05

Exaskryz wrote:@Stamimail, I think that's a problem.

What defines a useful script for anyone?...
+1
Recommends AHK Studio
lexikos
Posts: 9494
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

17 Oct 2017, 01:19

jonathan scott james wrote:i'm using xp, i cant seem to make the search function of help does not find parts of words
when i type a_tick , it cant find a_tickcount, it acts like it the search param has a space at the end and finds nothing.
It has nothing to do with XP. That's just how HTML Help search works. Merging #185 will fix it, by replacing the search mechanism.
Stamimail
Posts: 77
Joined: 06 Nov 2014, 08:48

Re: Suggestions on documentation improvements

17 Oct 2017, 13:24

> What defines a useful script for anyone?
I don't think this is difficult. What frequently be asked. What people complaints the OS is missing, and so on. You need to choose only one for each chapter..

In the case the documention, not going to be a guide for ahk (w3schools.com), you can make the "tutorial beginner"/intoduction different.

Inform the user that the documention/language is too huge for making a full guide to the language.
Inform the user that the learning is mainly community/forum based.

The user doesn't need to read tibdit "tutorial beginner" (oops...)

Teach the user, how to use the documention.
Don't learn what you don't need to learn/solve.
You have something to solve - GO Learn the soultion.

You want to make playing a game easier -- GO Learn Send, Click, and Sleep commands.
You want to build some kind of interactive record keeper or a digital timer -- GO Learn GUI.
You want to be able to play sound effects whenever keys are pressed on their keyboard -- GO Learn about SoundPlay.
You want to have a kind of JARVIS... - GO Learn ...
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

17 Oct 2017, 14:41

I think AHK functionality can be split into two:
- built-in functions/commands
- Winapi functions + anything else

for built-in functions/commands:
- there is already a page for each function/command
- there are a good number of examples per page
- here we need to anticipate some key useful examples to add
- there could be on average one or two more per page
- I've collected candidates for further examples here, I also mention tips on searching (decompile the chm, to search htms, and use the htms to create a single txt for searching):
jeeswg's documentation extension tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=33596
- I've listed various tutorials here:
jeeswg's homepage - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 17&t=30931

for Winapi functions + anything else:
- I'll try to collect some extended guidance for this
- e.g. DllCall, parameter types, UInt64 is currently Int64, endianness, signedness (irrelevant for write, relevant for read), bitness (x64/x32 affects structs/padding), Cdecl, Long/LongPtr functions, structs (e.g. padding: between items and trailing), listing functions in a dll
- MSDN website (a bit lacking for Gdip and msvcrt functions)
- C++: constants ('Windows Kits' folder contains .h files), get struct size
- looking at example scripts is the best way to learn, I've collected some links to example scripts for core topics here:
best utilities + best AutoHotkey scripts (+ useful tips) - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=28149
- I might take some topic headers such as text/images/sounds and give some general tips
- for text you might mention briefly: ini, JSON, html, RTF, csv/tsv, databases, Word/Excel, ANSI/Unicode, the clipboard, RegEx
- for other things I'll make some tutorials

- Ultimately you're asking a question like 'what you can do with C++, or what you can with programming?' If you're a beginner you can't give a good answer to this. If you're an expert it's hard to work out what to tell a beginner. Although my 'best scripts' page is an attempt.
- For games, I've been collecting various links relating to hotkeys, I might try and make a tutorial out of it with a large list of links, this is the one tutorial I'm not necessarily the best person for, e.g. I use an English keyboard and I don't use AHK for games, but I think I might attempt it (a general hotkeys tutorial with no games-related tips).
- Record keeper/digital timer aren't immediately obvious to me, they span various basic commands. Record keeper might be a candidate for FileAppend (or IniWrite), or perhaps you should ask on Ask For Help re. databases or JSON. I'm not sure what you mean by digital timer, perhaps Gui, otherwise FormatTime with a DllCall example if milliseconds/microseconds are required.
- JARVIS should be a new topic on Ask For Help.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
Stamimail
Posts: 77
Joined: 06 Nov 2014, 08:48

Re: Suggestions on documentation improvements

17 Oct 2017, 16:26

Sorry for not knowing the real answer, but perhaps the answer is:
AutoHotkey is not good to be learned as your first programming language.
AutoHotkey is best to be learned as your second programming language.
For beginners, AutoHotkey is the best place to find fast and easy programming solutions to their problems.
Is this correct?
User avatar
Exaskryz
Posts: 2882
Joined: 17 Oct 2015, 20:28

Re: Suggestions on documentation improvements

17 Oct 2017, 18:14

Stamimail wrote:Sorry for not knowing the real answer, but perhaps the answer is:
AutoHotkey is not good to be learned as your first programming language.
AutoHotkey is best to be learned as your second programming language.
For beginners, AutoHotkey is the best place to find fast and easy programming solutions to their problems.
Is this correct?
I think AHK is great as a first programming language. Admittedly, it's not my first langauge. I self-taught myself a little bit of XML, a little bit of HTML, and a little bit of CSS before diving into AHK. But AHK opened up a heck of a lot more doors for me.

--

As for the idea, getting the most common ideas could be done... and it has been. There are big tutorial threads that covered common topics, for example, an autoclicker: (Note: The first link is from the old forums, the second link is on these forums) http://www.autohotkey.com/board/topic/6 ... re-thread/ or https://autohotkey.com/boards/viewtopic.php?f=7&t=11952

And in part, that's potentially a problem. A tutorial enshrined in the documentation may be considered the "gold standard". It may limit the approaches people take for creative thinking. The first link shows at least 5 different ways to build your autoclicker, whereas the second one focuses on only 2. Which guide is better to feature?

I don't think it's a bad idea to have these resources -- these tutorials; I just think it's better located in the forums. If the documentation doesn't already have a section for instructing users to come visit the forums for help requests or discovering commands or project ideas, I'm in support of that being added. But I have a feeling it's in there somewhere.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

17 Oct 2017, 19:01

Compared to other things I tried, AutoHotkey had the advantage of being both easy and powerful.
- Some things are easy but not powerful, e.g. limited functionality (QBasic) or specific to a particular program (Excel VBA).
- Traditional programming languages are often powerful, but not easy. But worse than that, you waste your time doing pointless things, even when you know the language well. Those things can also clutter up the code making it less readable. These languages are *unnecessarily* difficult.

I believe that AutoHotkey is a good candidate to be learned as your first programming language.
Criteria would be:
- ease of learning
- ease of writing
- speed of compiling (you don't have to compile in AHK)
- speed of execution (AHK is fast, and you can write machine code functions where needed)
- can do everything you want (built-in and/or by using command-line applications where needed)
- you learn about core programming concepts and common notations
- you learn about the Winapi by using DllCall
- you learn about C++ by reading the source code
- you learn about other programming languages when you have advanced general queries and search online
- employability / reputation amongst employers/programmers (this should be helped by AHK v2, or by at least making function versions of all commands available in AHK v1)
- installation of under 2 MB
- good documentation
- good forum
- learning any programming/scripting/markup language has its advantages, and there are commonalities between them, if you spend a few months/years learning a language which you later abandon, it's unlikely to have been a wasted experience, especially if it's a reasonably well-known language

Other points to consider:
- cross-platform
- programming languages common in specific fields

If anyone has any other candidate languages that are both powerful and easy, I would be interested to hear.

Btw I think it might be a good idea to split this topic, to create 'Suggestions for a beginner tutorial'.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
User avatar
tidbit
Posts: 1272
Joined: 29 Sep 2013, 17:15
Location: USA

Re: Suggestions on documentation improvements

17 Oct 2017, 20:20

Stamimail wrote:The user doesn't need to read tibdit "tutorial beginner" (oops...)

Teach the user, how to use the documention.
Don't learn what you don't need to learn/solve.
You have something to solve - GO Learn the soultion.

You want to make playing a game easier -- GO Learn Send, Click, and Sleep commands.
You want to build some kind of interactive record keeper or a digital timer -- GO Learn GUI.
You want to be able to play sound effects whenever keys are pressed on their keyboard -- GO Learn about SoundPlay.
You want to have a kind of JARVIS... - GO Learn ...
thats not a tutorial. what you want is a categorized list of things and related commands.
like:

Code: Select all

Commonly used for gaming:
- thing 1
- thing 2
- thing ...
Commonly used for macros:
- thing 1
- thing 2
- thing ...
Commonly used for work automation:
- thing 1
- thing 2
- thing ...
Commonly used for <category>:
- thing 1
- thing 2
- thing ...
I believe this was done before, quite an extensive list. forgot where it was though. Was it on the wiki when we had one? or github?
rawr. fear me.
*poke*
Is it December 21, 2012 yet?

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 6 guests