[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
Stamimail
Posts: 77
Joined: 06 Nov 2014, 08:48

Re: Suggestions on documentation improvements

18 Oct 2017, 14:25

I think that for learning AHK as a first language you need to "write a book".
I only suggested, that the examples used in this book, for explaining each chapter, will be useful example/tool.
(You can think also about giving an advanced script, and telling the user to focus for this chapter learning in some 3 lines)
While writing each chapter:
The first question is: What do I want that the user will know by reading this chapter.
The second question is: Which script is good to use for explaining the chapter goals, and giving the user useful tool.

In this way:
1. the user will learn the chapter (the main goal)
2. the user will have a useful tool, that will encourge him to go on in reading the book, and exploring more about the chapter and its relative commands, for customize his tool.

If there is no book, the user has no choice but to learn by "looking for solutions" method.
Stamimail
Posts: 77
Joined: 06 Nov 2014, 08:48

Re: Suggestions on documentation improvements

25 Oct 2017, 13:32

If there is no book, the user has no choice but to learn by "looking for solutions" method.
Now that I'm thinking about it... years ago I had an idea, which if had been implemented then, I think my progress in AHK and my skills now would have been completely different.

https://autohotkey.com/boards/viewtopic.php?t=5152
User avatar
Exaskryz
Posts: 2882
Joined: 17 Oct 2015, 20:28

Re: Suggestions on documentation improvements

04 Nov 2017, 09:07

https://autohotkey.com/docs/misc/RemapJoystick.htm

On this page, at the top, it makes the recommendation to use the software PPJoy if you would like to make artificial joystick output. (Remap keys -> joystick; AHK is only capable of joystick -> keys). However, following the hyperlink points us to a geocities page which is now debunk and results in redirecting to a "smallbusiness.yahoo.com"

I have seen people suggest software to use for people requesting being able to produce artificial joystick output. Maybe updating the docs to recommend one of those software would be good, or someone knowing of a good site to download PPJoy from today?
egocarib
Posts: 100
Joined: 21 May 2015, 18:21

Re: Suggestions on documentation improvements

08 Nov 2017, 13:38

MonitorGet (AHKv2) should be moved from the Misc. sidebar section to the Screen sidebar section.
egocarib
Posts: 100
Joined: 21 May 2015, 18:21

Re: Suggestions on documentation improvements

08 Nov 2017, 15:57

Also, would be great if the v2 documentation site search bar was updated to show you search results for the v2 documentation, instead of redirecting you to results on the v1 documentation website.
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

09 Nov 2017, 04:56

egocarib wrote:MonitorGet (AHKv2) should be moved from the Misc. sidebar section to the Screen sidebar section.
I've created a pull request on GitHub for this issue.
egocarib wrote:Also, would be great if the v2 documentation site search bar was updated to show you search results for the v2 documentation, instead of redirecting you to results on the v1 documentation website.
The v2 documentation will soon receive the new sidebar from the v1 documentation, including its own search.
egocarib
Posts: 100
Joined: 21 May 2015, 18:21

Re: Suggestions on documentation improvements

09 Nov 2017, 18:14

Nice - I hadn't noticed the new sidebar and format updates. They look awesome! :thumbup:
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

10 Nov 2017, 13:27

Exaskryz wrote:On RemapJoystick.htm, at the top, it makes the recommendation to use the software PPJoy if you would like to make artificial joystick output. (Remap keys -> joystick; AHK is only capable of joystick -> keys). However, following the hyperlink points us to a geocities page which is now debunk and results in redirecting to a "smallbusiness.yahoo.com"
just me wrote:ControlGet -> Choice: ; It will be -1 if there is no item selected. is definitely wrong for 32-bit AHK because SendMessage returns an UINT value (4294967295 in this case).
just me wrote:The Standard Windows Fonts page contains outdated information and shoud be updated, removed, or replaced by an external link (I didn't find any useful).
TAC109 wrote:format() is missing from the list of built-in functions.
nnnik wrote:InsertAt example: ; This is the new "position" of "B" should be ; This is the new "position" of "A"
Fixes/changes/additions for these issues can be found in another pull request on GitHub.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

11 Nov 2017, 04:53

Fragment identifiers.
- It would be good to have direct links available for each code example at the bottom of a page e.g.
Run / RunWait
https://autohotkey.com/docs/commands/Run.htm#ExecScript
Each code example would need some sort of meaningful identifier, and not something like '#Example1', in case the examples were shuffled/added to.
- Alternatively, is there some url suffix available to jump to the specified string if it exists. I would happy with this solution instead.

Scrolling.
Since the website was updated, when I open the page, I cannot scroll up or down with the arrow keys etc.

Thanks for reading.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
egocarib
Posts: 100
Joined: 21 May 2015, 18:21

Re: Suggestions on documentation improvements

11 Nov 2017, 13:40

jeeswg wrote:Fragment identifiers.
- It would be good to have direct links available for each code example at the bottom of a page e.g.
Run / RunWait
https://autohotkey.com/docs/commands/Run.htm#ExecScript
I agree that it would be a nice enhancement. Though I don't think it is a significant issue. If you're directing someone else to an example, you can usually just link to #Examples and add provide a short description of which one you're referring to. I took a quick look and these seem to be the only pages with ~40 or more lines in the example section. If someone does want to add anchors, these would most likely be the pages to focus on. A few of these already have anchors to their individual examples.
Spoiler
jeeswg wrote:Scrolling.
Since the website was updated, when I open the page, I cannot scroll up or down with the arrow keys etc.
Seems to be related to the new sidebar change. The focus isn't on the main content now when you load a page. If you click in the main content area, you can then scroll with up/down arrows. Ragnar might know how to fix this.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

11 Nov 2017, 15:55

- The mouse wheel works to scroll the window fine, but even when I click in the middle area or scrollbar, up/down, PgUp/PgDn don't scroll. Tested on Internet Explorer 11. At least I can create an AHK script to handle the website: Send, {WheelDown}.
- Your suggestion to focus on fragment identifiers for pages with a lot of examples is fine.
If you're directing someone else to an example, you can usually just link to #Examples and add provide a short description of which one you're referring to.
- I was doing this and it was getting incredibly tiresome. It's also an issue if I want to revisit that example myself, and I have to find it again. A jump to the first occurrence of a string, if simple/possible, would be a general solution, that wouldn't require editing multiple webpages.

Link:
list fragment identifiers on a webpage (hash that jumps to point) - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=28053
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
Barney
Posts: 55
Joined: 28 May 2014, 20:03
Location: Germany

Re: Suggestions on documentation improvements

13 Nov 2017, 23:56

For BlockInput it says
BlockInput On might have no effect if UAC is enabled and the script has not been run as administrator.
After reading this I was under the impression only Mode 1 is affected, but actually BlockInput, Send, i.e. Mode 2, is affected, too.
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

14 Nov 2017, 12:08

jeeswg wrote:Scrolling.
Since the website was updated, when I open the page, I cannot scroll up or down with the arrow keys etc.
Should be fixed. You can test it in the German docs. Note that Edit and ListBox in the Index and Search tab remain focused when used.
jeeswg wrote:The mouse wheel works to scroll the window fine, but even when I click in the middle area or scrollbar, up/down, PgUp/PgDn don't scroll. Tested on Internet Explorer 11.
I don't have any problems with that. It even works in IE8 on Windows XP.
jeeswg wrote:A jump to the first occurrence of a string, if simple/possible, would be a general solution, that wouldn't require editing multiple webpages.
Do you already know CTRL+F? ;) Otherwise, I think egocarib's suggestion is sufficient: Link to #Examples and add a short description. But I don't want to stop anyone from making this change at GitHub.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

14 Nov 2017, 13:24

@Ragnar:
- Great, it didn't work in the English docs, but did in the German docs, working nicely. (Navigation with arrow keys on the website in Internet Explorer 11.)
- If there's a standard for a url that in effect did what Ctrl+F does, that would be great, I'd like it for my website.
- I needed some sort of radical solution re. examples, I looked back at urls I'd made to the examples sections of pages, and seeing that adding fragment identifiers to every example is not necessarily easy or something I want to do depend on ... The best solution is actually to copy and paste the code, once I've found it, to the forum post, or to my text files, to save people having to navigate to it in the help file, and to save having to think about what text to copy and paste, to uniquely identify the example. (It actually often takes a while when looking at an example, to find some good candidate text for Ctrl+F.)
- Feel free to use information from here in the documentation, modified as much or as little as you want. E.g. 'Format function examples'.
jeeswg's documentation extension tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=33596
- Btw I don't see DirExist or Exception here (e.g. FileExist / DirExist, Throw / Exception):
Alphabetical Function Index
https://lexikos.github.io/v2/docs/commands/index.htm
- So you've done a lot of good things with the documentation, what've you got planned? 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
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

15 Nov 2017, 09:02

Barney wrote:After reading this I was under the impression only Mode 1 is affected, but actually BlockInput, Send, i.e. Mode 2, is affected, too.
You're right. I've changed the line to Mode 1 and 2 might have no effect... and add it to the pull request on GitHub.
jeeswg wrote:Btw I don't see DirExist or Exception here (e.g. FileExist / DirExist, Throw / Exception):
I've added Exception to v1's command and function list (which will be later automatically integrated into the v2 docs), and DirExist to v2's function list.
User avatar
derz00
Posts: 497
Joined: 02 Feb 2016, 17:54
Location: Middle of the round cube
Contact:

Re: Suggestions on documentation improvements

02 Dec 2017, 08:48

Should there not be a index item for A_Args (v2 only)? There is one parameters passed to a script, which gets you pretty close.... But if A_Args is a thing, it should be in the index
try it and see
...
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

02 Dec 2017, 17:45

derz00 wrote:Should there not be a index item for A_Args (v2 only)?
It should. Added to pull request on GitHub.
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

10 Dec 2017, 10:51

ragnar, good work with the docs updates

joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

10 Dec 2017, 13:21

WinMove - parsing problem should be documented

The following script produces an error. Specifically "Missing ]".

winmove, KEDIT - [, , 15, 43, 1316, 954

Because the WINMOVE command has 2 syntaxes, the parser has a problem. While the above is a valid syntax for the WINMOVE command (2nd version, with more than 2 parameters), the parser sees the "[" as the beginning of the definition of an array.
This is discussed at https://autohotkey.com/boards/viewtopic ... 14&t=41101

Additionally, the workaround could be documented (again, see the discussion).

Thank you

Joe Petree

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 10 guests