Documentation formatting changes?

Discussion about the AutoHotkey Foundation and this website
nimda
Posts: 34
Joined: 18 Dec 2013, 14:06

Documentation formatting changes?

30 Apr 2014, 19:43

I find the new formatting to be disorganized and very hard to read. Compare:
http://www.autohotkey.com/docs/commands/Run.htm
http://ahkscript.org/docs/commands/Run.htm

Tables are much better for presenting tabular data, IMHO.
lexikos
Posts: 5598
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Documentation formatting changes?

03 May 2014, 19:42

I don't.

I also don't consider that to be tabular data any more than the overall document is tabular data.
Zelio
Posts: 275
Joined: 30 Sep 2013, 00:45
Location: France

Re: Documentation formatting changes?

03 May 2014, 20:30

Perhaps, to add an half line between parameters (separation), and don't align parameter with title, more move to right (tab), and a smaller font.

Samples of Standards:
http://www.w3schools.com/jsref/jsref_obj_regexp.asp
http://msdn.microsoft.com/en-us/library ... regex.aspx
http://msdn.microsoft.com/en-us/library/hh160264.aspx (without table, but tab)

Do as you wish, but if you want to improve the learning curve then use the whole brain, even for memory or understanding:
- unusual fonts (http://web.princeton.edu/sites/opplab/p ... r_2010.pdf)
- colors (http://en.wikipedia.org/wiki/Synesthesia)
- visual (table or group, hierarchy, geometric, page layout(title,paragraph), readability, etc...)
just me
Posts: 4956
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Documentation formatting changes?

04 May 2014, 01:46

I like the new look of the documentation. Maybe the section headers could be a bit more visual outstanding.
IMHO, the table style is more approppriate for short syntax references without additional remarks and samples.
AHK 1.1.25.02
tmplinshi
Posts: 1094
Joined: 01 Oct 2013, 14:57

Re: Documentation formatting changes?

04 May 2014, 06:38

I like the new style too, it looks much more beautiful, and makes me wanted to read.
User avatar
fincs
Posts: 500
Joined: 30 Sep 2013, 14:17
GitHub: fincs
Location: Seville, Spain
Contact:

Re: Documentation formatting changes?

04 May 2014, 11:01

tmplinshi wrote:I like the new style too, it looks much more beautiful, and makes me wanted to read.

+1. The old style was getting old, and it's very nice to see fresh and new CSS. As soon as I saw it being committed, I immediately adopted it for GenDocs and ScITE4AutoHotkey's documentation.
fincs
Windows 10 x64 Build 14393 / AutoHotkey v1.1.24.04
Get SciTE4AutoHotkey v3.0.06.01 - [My project list]
guest3456
Posts: 2119
Joined: 09 Oct 2013, 10:31

Re: Documentation formatting changes?

04 May 2014, 12:23

the old style was getting old, but it was easy to read at a quick glance

this new style is absolutely horrible. i have to put in effort to determine where the information is. that is bad style.

is the change for purely aesthetic purposes? because there seems to be very little functional benefit to this change. its way harder to read. i have no idea what that other guy is talking about because when i look at the new page, it makes me want to close it immediately. i dont want to struggle to find a parameter or heading

vasili111
Posts: 733
Joined: 21 Jan 2014, 02:04
Location: Georgia

Re: Documentation formatting changes?

04 May 2014, 13:12

Old style is much easier to read. New style is not as ergonomic as old one.
DRAKON-AutoHotkey: Visual programming for AutoHotkey.
timeFlies
Posts: 146
Joined: 22 Oct 2013, 20:54
Location: Somewhere in the northern hemisphere.

Re: Documentation formatting changes?

05 May 2014, 19:25

Headings need to be more prominent, preferably with the bar running the width of the page like in the old CSS.
User avatar
DataLife
Posts: 194
Joined: 29 Sep 2013, 19:52

Re: Documentation formatting changes?

06 May 2014, 18:13

guest3456 wrote:the old style was getting old, but it was easy to read at a quick glance

this new style is absolutely horrible. i have to put in effort to determine where the information is. that is bad style.

is the change for purely aesthetic purposes? because there seems to be very little functional benefit to this change. its way harder to read. i have no idea what that other guy is talking about because when i look at the new page, it makes me want to close it immediately. i dont want to struggle to find a parameter or heading

I agree completely.

Will this be the formatting for the offline documentation?
Check out my scripts. (MyIpChanger) (XPSnap) (SavePictureAs)
All my scripts are tested on Windows 7, AutoHotkey 32 bit Ansi unless otherwise stated.
lexikos
Posts: 5598
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Documentation formatting changes?

06 May 2014, 18:51

guest3456 wrote:this new style is absolutely horrible.
You are entitled to your opinion. However, I'm not going to change everything back just because you hate it. If you have some constructive suggestions, let's hear them.
i have to put in effort to determine where the information is.
Why is that? I don't.
i dont want to struggle to find a parameter or heading
Are you colour-blind? Because if you are, I can see how it might be slightly more difficult.

just me wrote:Maybe the section headers could be a bit more visual outstanding.
Which section headers? The colourful headings?

Zelio wrote:Perhaps, to add an half line between parameters (separation), and don't align parameter with title, more move to right (tab), and a smaller font.
Thanks for the suggestions. None of the other sections are indented further than the heading; why indent the parameter section? Smaller font where and why? The overall font size was originally 75%, but I think that's just too small on modern displays.

I'm not really sure why I put the line next to each parameter. Maybe it would be clearer without them.

timeFlies wrote:Headings need to be more prominent, preferably with the bar running the width of the page like in the old CSS.
I disagree. Perhaps that makes it easier to see where one section ends and the next begins when you're not looking at the start of the line, but exactly how is that useful? If you're reading the documentation, you'll see the end of the section. If you're looking for a section, you'll be looking to the left to read the section names, and in that case the headings are easily distinguishable from the rest of the text.
timeFlies
Posts: 146
Joined: 22 Oct 2013, 20:54
Location: Somewhere in the northern hemisphere.

Re: Documentation formatting changes?

07 May 2014, 00:22

lexikos wrote:I disagree...


You would be right if the green headings were easily distinguishable and easy to read, but (to me at least) they are not. I suggest making the headings more prominent by increasing the text size slightly, using a darker colour, or introducing a slightly larger paragraph space before the heading.

Other than that I see no problem with it. If anything, it's more visually appealing. Keep those vertical lines in the parameter list; they draw together and directly link the description with the parameter name, especially if the description is many paragraphs long.
just me
Posts: 4956
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Documentation formatting changes?

07 May 2014, 03:28

lexikos wrote:
just me wrote:Maybe the section headers could be a bit more visual outstanding.
Which section headers? The colourful headings?

Yes, those light-coloured headings.
AHK 1.1.25.02
User avatar
Sidola
Posts: 14
Joined: 10 Oct 2013, 14:14
GitHub: Sidola

Re: Documentation formatting changes?

07 May 2014, 11:59

Have to say I agree with the people saying the new design is a bit hard to follow.
I think those full-width backgrounds for the headers really helped structure the page when you had to skim it.

Another example would be these two pages:
http://www.autohotkey.com/docs/Hotkeys.htm
http://ahkscript.org/docs/Hotkeys.htm

I'm also missing the tabular design for the parameters, but that could just be because I'm so used to it by now.
Zelio
Posts: 275
Joined: 30 Sep 2013, 00:45
Location: France

Re: Documentation formatting changes?

07 May 2014, 13:30

It was just some throughts, the real problem is about habits, but something is missing...
This forum, MSDN, or any other common docs appear like a 13px font, on my computer it is like a 80% (19" screen 1440*900), not like the new 90% (I assume to use a body at 100% and 0.8em to create a 80% font, and it will be better to play with body size percent for mobil)

Code: [Select all] [Expand] [Download] GeSHi © Codebox Plus


For example, I guess it is a good readability with a small font and extra space or line, http://msdn.microsoft.com/en-us/library/hh160264.aspx
Also a high line-height trends to break blocks... It is very rare to read news or other article with this feature, so bad habit too, or it is about famous people or blog to pretend to have much to say.
But again, do as you wish, any work gave to the manual will be good, the documentation need a rebirth !
lexikos
Posts: 5598
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Documentation formatting changes?

07 May 2014, 23:20

timeFlies wrote:You would be right if the green headings were easily distinguishable and easy to read,
They are to me, hence my disagreement. But that's only a part of my point.
I suggest making the headings more prominent by increasing the text size slightly, using a darker colour, or introducing a slightly larger paragraph space before the heading.
Thanks for the suggestions. FYI, the green comes from the ahkscript home page.

Sidola wrote:Another example would be these two pages:
http://www.autohotkey.com/docs/Hotkeys.htm
http://ahkscript.org/docs/Hotkeys.htm
Another example of what? The "full-width backgrounds for the headers" were on most pages, so I don't know why you'd single out those two if that's what you're referring to.

Zelio wrote:This forum, MSDN, or any other common docs appear like a 13px font,
Different sections at MSDN use different styles. For instance, windows/desktop uses .875em, which computes to 14px on this system. Anyway, I don't see a need to copy the font size from other documentation. I just set the font size based on what is comfortable to my eyes; the old font was too small and cramped.
For example, I guess it is a good readability with a small font (...)
I'm not sure what you're trying to say, but to me that sounds contradictory. I'm sure some people find small fonts readable, but can't understand how anyone would find a slightly larger font less readable.
guest3456
Posts: 2119
Joined: 09 Oct 2013, 10:31

Re: Documentation formatting changes?

08 May 2014, 01:01

lexikos wrote:
guest3456 wrote:this new style is absolutely horrible.
You are entitled to your opinion. However, I'm not going to change everything back just because you hate it. If you have some constructive suggestions, let's hear them.


certainly don't do anything just because of my opinion alone. but the existence of the thread means i'm not alone.

i'm not great with design/usability/UX/etc, so unfortunately i can't really give good suggestions. my perspective is simply from an end user. things are way harder to read, imo. looking at the two pages, i guess the differences are the horizontal lines to separate sections: the <hrs>, <tables> for parameters, and background color of the headings all made things much easier, for me

i'm usually in the "if it aint broke don't fix it" camp. i'm surprised that this change was even made because usually you're (smartly) not wasting time working on stuff that doesn't have a good reason behind it

better question would be, what was wrong with the original formatting? thats why i asked if this was purely for aesthetics

User avatar
Sidola
Posts: 14
Joined: 10 Oct 2013, 14:14
GitHub: Sidola

Re: Documentation formatting changes?

08 May 2014, 04:37

lexikos wrote:
Sidola wrote:Another example would be these two pages:
http://www.autohotkey.com/docs/Hotkeys.htm
http://ahkscript.org/docs/Hotkeys.htm
Another example of what? The "full-width backgrounds for the headers" were on most pages, so I don't know why you'd single out those two if that's what you're referring to.


True, I was mostly just clicking around and found that the difference between those two pages did a good job of illustrating how the header backgrounds helped.

I'll do a decent mock-up when I get home of how I think it could be improved, I understand having people just saying it looks "bad/wrong" isn't very helpful.

Finally home, mock-up:
Changes:
- Black H1 font (personal preference)
- Moved nav to above H1 header to avoid wrapping on long titles
- Added a 2px border beneath each chapter-header
- Added a gray background to each minor-header, and changed the font to black here, green clashed with the gray
- Changed font-size to 80%

Hotkeys page, example 1
Hotkeys page, example 2

Run command page, example 1
Run command page, example 2

Having the parameters in a list format rather than table still feels a bit weird, but I think that's mostly because I'm used to reading it in a table-format. Having a list format for them actually makes sense on more complex parameters where the explanations can get lengthy.
timeFlies
Posts: 146
Joined: 22 Oct 2013, 20:54
Location: Somewhere in the northern hemisphere.

Re: Documentation formatting changes?

08 May 2014, 22:09

lexikos wrote:FYI, the green comes from the ahkscript home page.


Aha! I see now why you did it that way. It looks aesthetically good, but just like most people prefer code displayed in mono-spaced font (which is nothing but ugly), practicality usually takes priority in cases like this (eg documentation).
User avatar
nnnik
Posts: 2392
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Documentation formatting changes?

08 May 2014, 22:41

I like it.
I'm not sure but isn't it Ragnars design?
Recommends AHK Studio

Return to “About This Community”

Who is online

Users browsing this forum: No registered users and 7 guests