Documentation formatting changes?

[nimda]

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]

I don't.

I also don't consider that to be tabular data any more than the overall document is tabular data.

[Zelio]

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]

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.

[tmplinshi]

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

[fincs]

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.

[guest3456]

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]

Old style is much easier to read. New style is not as ergonomic as old one.

[timeFlies]

Headings need to be more prominent, preferably with the bar running the width of the page like in the old CSS.

[DataLife]

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?

[lexikos]

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.

Maybe the section headers could be a bit more visual outstanding.

Which section headers? The colourful headings?

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.

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]

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]

Maybe the section headers could be a bit more visual outstanding.

Which section headers? The colourful headings?

Yes, those light-coloured headings.

[Sidola]

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]

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

<!DOCTYPE html>
<html>
<head>
<style>
body{font-size:100%;}
p{font-family:arial;font-size:0.8em;}
</style>
</head>
<body>
<p>This is a paragraph.</p>
</body>
</html>

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]

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.

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.

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]

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

[Sidola]

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]

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).

[nnnik]

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