[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

29 Oct 2019, 05:13

jeeswg wrote:
26 Oct 2019, 06:55
#SINGLEINSTANCE
- 'Prompt' is listed in AHK v2.
- 'Prompt' could/should be listed in AHK v1.
- (In AHK v1, '#SingleInstance prompt' works, although it is not explicitly defined in the source code, see SINGLE_INSTANCE_PROMPT.)
There is no "Prompt" parameter in v1. Everything except "Force", "Ignore" and "Off" causes the prompt mode. That is, you might as well write #SingleInstance ewrewrwe or #SingleInstance whatever to achieve the same effect. I'll clarify it in the docs.
User avatar
lmstearn
Posts: 688
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

07 Nov 2019, 23:10

The filesystems in DriveGet don't include ExFat. By what MS-FSA suggests, the flags are the same as FAT32.
Spoiler
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH
john_c
Posts: 493
Joined: 05 May 2017, 13:19

Re: Suggestions on documentation improvements

11 Nov 2019, 02:19

ClipWait page says that

> Specifying 0 is the same as specifying 0.5.

It looks (erroneously) that 0.5 is the minimum possible value.

Actually, it is not, as Helgef shown today:

Code: Select all

clipboard := ""
t1 := a_tickcount
clipwait 0.05
t2 := a_tickcount
msgbox % t2-t1
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

11 Nov 2019, 02:24

As I told you, that doesn't say that the minimum is 0.5, that was your erroneous interpretation.
john_c
Posts: 493
Joined: 05 May 2017, 13:19

Re: Suggestions on documentation improvements

11 Nov 2019, 02:31

Helgef, yes, it was my erroneous interpretation, thank you. But it seems this erroneous interpretation was a consequence of not-very-clear text on the page, isn't it? (Of course, other people could say that text is already clear enough.)
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

11 Nov 2019, 07:08

- @Helgef: I'd really like it if you could try and understand other points of view about the documentation.
- E.g. standards such as: 'abundantly clear' / 'not misleading' / 'unlikely to be misinterpreted'.
- I felt exactly the same way as john_c, when I first came across this. It's *very* misleading, unacceptably so. It's unclear, and likely to be misinterpreted.
- I also felt that 0 being equivalent to 0.5 broke the principle of least astonishment. Because of this, I felt compelled to run multiple tests on ClipWait.

Code: Select all

Clipboard := ""
vTickCount := A_TickCount
ClipWait, 0.1
MsgBox, % A_TickCount - vTickCount
- I might add something like: 'E.g. specify 0.1 to wait a maximum of approximately 100 milliseconds.'
- Btw, and this is important, English is not everyone's first language.
- Also, the way you made your comments to john_c, if you can't get something like that right, it further hurts your case when talking about how the documentation should be. You have to aim slightly higher.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

11 Nov 2019, 08:33

how is the documentation unclear? in the most concise way possible it literally says "this arg accepts floats. if u pass 0 in, it will behave as though u passed 0.5 in"
there's no mention of there being a minimum or anything, it literally means exactly what it says.
id understand it if u made a case about the command's behavior being astonishing. it probably is. and it probably is also justified in some way, im sure if u dug back far enough ud find some very very very old reasons for why it is so. but don't see how u can say the docs are at fault. don't ascribe additional meaning to stuff where there is none
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

11 Nov 2019, 08:44

- As a general rule, anything unintuitive should be acknowledged as such in some way.
- If people suspect that the way something is written has led or will lead to the wrong interpretation, amendments should be considered.
- I suggested a one-line addition, by using 0.1 as an example, this demonstrates that 0.5 is not the minimum value, but avoids a long/verbose explanation.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

11 Nov 2019, 09:37

- and it already is
- misinterpretations on account of the user, not the docs
- what are u gonna do about the people assuming 0.1 now is the new "minimum"?
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

11 Nov 2019, 09:45

If a sentence is commonly misinterpreted the fault lies within the docs.
I also thought that 0 behaving as 0.5 means that there cannot be a smaller value than 0.5.
keep in mind that for many users there is a language barrier involved.

Attempt at rephrasing:
0 will behave as though the value of 0.5 was passed. Passing values lower than 0.5 is possible by using float values greater than 0.
Recommends AHK Studio
User avatar
haichen
Posts: 631
Joined: 09 Feb 2014, 08:24

Re: Suggestions on documentation improvements

11 Nov 2019, 09:49

@jeeswg ++
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

11 Nov 2019, 09:53

- @swagfag: 'misinterpretations by multiple users (and uncertainty), caused by the docs (in a way that could be easily anticipated)'.
- Your conception that people might assume 0.1 as the minimum, helps to confirm my point, and I did take that into account. Anything lower than 0.1 is pretty much negligible, so it essentially doesn't matter. We could use 0.05 or 0.02 instead. 0.01 is a bad example because granularity issues come into play. (I.e. on many systems wait times tend to be in multiples of around 16 msec.)
- I considered most/all points of view and came up with a simple one-line addition. Even the one-line addition leaves potential ambiguity, but I felt it addressed the issue without unnecessary verbosity.

- (Btw ClipWait, n, 1 informs you whether the clipboard is completely empty or not. And ClipWait, 0, 1, where 0 actually meant 0, would tell you this instantly. This could be a good change for AHK v2, and I could implement this in my 'AHK v2 functions for AHK v1' library.)

- @nnnik: Good suggestions. Thanks.
- @haichen: Thanks.
Last edited by jeeswg on 11 Nov 2019, 14:24, edited 1 time in total.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

11 Nov 2019, 12:57

@nnnik
agreed, there might be a language barrier, which is also why u should be extra mindful of any word-saladdy addendums further compounding said language barrier issues

@jeeswg
- people, just read what it says, for crying out loud. dont read into what it doesnt say. dont derive meaning from things that arent there. "Specifying 0 is the same as specifying 0.5" is literally all it says and from that u infer that the minimum is 0.5? "well if i specify 0.1, then it surely must be the same as specifying 0.5, hurr". what??? do u notice how it doesnt say "Specifying floating point values in the interval range [0, 0.5) {will get clamped to | ceil-ed to | is the same as specifying} 0.5"? i hope so
- okay, mr. arbiter of whats negligible and what isnt. there is a "minimum"(a funny looking many-zeroed float probably) and then there is the actual minimum(GetTickCount resolution + however long running the function takes + whatever other shit is going on in the background with ur computer). do u really want to open the can of worms that is this implementation detail?
- u urself acknowledge the flaws(which had already been pointed out earlier) in that its ambiguous, yet in the very same breath proclaim that the issue has been addressed! im confused through and through. i must be now living in the berenstain-cognitive-dissonance universe. i cant explain it otherwise

- so, ClipWait + magic number = IsClipboardEmpty? good change for AHK v2? :lol: yeah, i dont think so. though i concede, there is utility in having this functionality. so heres a "gooder change for AHK v2" instead: Clipboard, ClipboardAll, ClipWait and all other clip related stuff, i might be forgetting, finally get consolidated into one Clipboard object with .IsEmpty, .Text, .Data etc properties and .Wait(...) etc methods
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

11 Nov 2019, 13:36

Yeah do you think that my formulation is less clear then the current one?
I think the documentation lacks clarity here and I want to make it clear by adding an extra sentence.
Do you think that this approach is unreasoneable? If so what would you suggest? Hope that people start understanding it like it is?

I don't think that this is the place to start a discussion about potential new features or changes to existing ones.
(Though I like the idea)
Recommends AHK Studio
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

11 Nov 2019, 14:46

- @swagfag: Nice use of 'clamped'.
- script2.cpp says this, I half-agree, however, they didn't consider WaitForAnyData, i.e. if the clipboard is *completely* empty:
// Waiting 500ms in place of a "0" seems more useful than a true zero, which
// doesn't need to be supported because it's the same thing as something like
// "IfWinExist". A true zero for clipboard would be the same as
// "IfEqual, clipboard, , xxx" (though admittedly it's higher overhead to
// actually fetch the contents of the clipboard).
- In documentation, there is a balance between clarity and verbosity. All things considered, I concluded that giving an example value below 0.5, and about as close to 0 as was likely useful, was for the best. I tend to propose either no fix, or the minimum fix.
- Already, in AHK v1, ClipWait, n, 1 is effectively IsClipboardEmpty, I clarified my post above.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

12 Nov 2019, 02:41

There is no misunderstanding due to language here, I doubt anyone's English in this discussion, is so poor that you read x implies y as y is minimum, either you understand the very simple sentence, or you don't. The misunderstanding stems from human brain behaviour, that is, since the command's behaviour (0 implies 0.5) is so senseless, the human brain will try to fix it, 0 makes sense as a minimum (minimum is now in your brain) but since it implies 0.5 (which everyone actually understood), it becomes the minimum, your brain has fixed the quirk. This type of behaviour is why we can make sense of, eg, hearing only part a sentence when someone talks to us and a bus passes, making the middle of a sentence inaudible, our brains will use context and passed experiences to fill in the missing pieces and make sense of what is missing, sometimes it deceives us.

I did not oppose any suggestions of changes to the documentation, there were non at the time of my previous post, I only remarked that there was no error in the docs, only an erroneous interpretation.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

12 Nov 2019, 03:18

The behaviour does get amplified by language barriers though.
To me causing a misinterpretation just means that the docs did not communicate correctly.
Recommends AHK Studio
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

12 Nov 2019, 08:30

since the command's behaviour (0 implies 0.5) is so senseless, the human brain will try to fix it
Great description. Attempts to ponder what the behaviour is, and why, could last half-an-hour or more.
As I told you, that doesn't say that the minimum is 0.5, that was your erroneous interpretation.
Maybe in your jurisdiction, it's different, but 'As I told you' and 'your erroneous interpretation', sound a bit like: 'I am smart, you are dumb, I am patronising you'. Ways to avoid sounding like that might be: 'I partially agree', or, 'people could misinterpret', and avoid anything, no matter how trivial the mistake, like 'you made a mistake' or 'you did something wrong'.

To me, it sounded like you were saying that the documentation was sufficiently/obviously clear, and thus that no change should be made. I.e. people usually post in this thread either (a) what should change, (b) should it change.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
john_c
Posts: 493
Joined: 05 May 2017, 13:19

Re: Suggestions on documentation improvements

12 Nov 2019, 09:11

Guys, I think we take the personal aspect here too serious.

Actually, it is better to think about:

* should or should not the ClipWait passage be rephrased
* and how. That't it.

Also, I found Google developer documentation style guide very useful.
john_c
Posts: 493
Joined: 05 May 2017, 13:19

Re: Suggestions on documentation improvements

19 Nov 2019, 03:24

From https://www.autohotkey.com/docs/commands/CoordMode.htm:

> Client [v1.1.05+]: Coordinates are relative to the active window's client area, which excludes the window's title bar, menu (if it has a standard one) and borders. Client coordinates are less dependent on OS version and theme.

Some people may think that "Client" is somewhat more reliable than "Window". Actually, it has its own weirdness.

Code: Select all

#SingleInstance, Force

; Tested on Windows 7 with Sublime Text, Notepad2-mod, LibreOffice Writer
CoordMode, Mouse, Window ; OK
CoordMode, Mouse, Client ; Not OK (clicks about 100 pixels below the window)

ClickRelativeToBottomRightCorner(X, Y) {
  WinGetActiveStats, Title, Width, Height, UpperLeftCornerX, UpperLeftCornerY
  X := Width - X, Y := Height - Y
  Click, %X%, %Y%
}

F2:: ClickRelativeToBottomRightCorner(0, 0)
client.png
client.png (48.51 KiB) Viewed 8301 times

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 10 guests