AutoHotkey Community

I think if the "CONTENT / INDEX" was moved to the right-hand side, it would make the documentation layout changes easier to consume. As is, we read left-to-right; there is no clear separation between the documentation body and the index.

So either:
1) Change the background color of the CONTENT/INDEX (darker) AND/OR
2) a vertical line separating the documentation and the Index. AND/OR
3) Move the INDEX to the right.

The only other comment, green for titles/h-tags seems odd, green has traditionally been the "comment" colour, for most editor's language syntax highlights and likewise for AHK script [

There already is a vertical line separating the documentation and the index.

I'm all for #1 or #3 if someone else wants to submit a pull request.

First of all it is a good idea to give a fresh look to a documentation. Here are some of my impressions and ideas.

1. I think that the main thing that can be improved in new documentation is that for parameters better to use table instead of a vertical line like now. Using table is more ergonomic way, easy to understand and read. It can be different kind of table, not necessary to have the table that was in old documentation.


2. The titles should also have some background:

Now:


Bettere to have something like:


OR





3. Code samples now have only background like here:


I think it is better also to make a border, like in tidbit documentation (I had to cut image, the example below should have green border also in right side):




4. Inline code also need to be more prominent:

Now is:



Better to have something like in tidbit documentation:




5. For separate actual text from buttons, tidbit also uses a image like buttons:



I think that it is good way to indicate buttons. But I think they should be more prominent that in tidbit tutorial.



6. I think that borders that separate one section of text from another should be more prominent and darker maybe also thicker. It should better visually separate one section of text from another. I mean that borders:




7. I think that links also should be slightly darker for easy visual separation from actual text.

vasili111, I disagree with #1 - 4. You seem to be describing (and in at least one case showing a screenshot of) the old documentation.

3. Contrary to what you say, your example image shows that they do not have only a background. There is a bottom border.

5. I don't particularly disagree, but it looks like a lot of work (finding and marking key names or hotkeys) for little reason.

7. The 'actual text' is black, so making the links darker would give them less 'visual separation from actual text'. However, it might make them easier to read.

+1 #5 but I think I could Make the keys look better than in the image, I might submit a pull request... We'll see...

lexikos wrote:You seem to be describing (and in at least one case showing a screenshot of) the old documentation.

The documentation is from here: http://ahkscript.org/docs/AutoHotkey.htm

lexikos wrote:3. Contrary to what you say, your example image shows that they do not have only a background. There is a bottom border.

Bad screenshot. They have background but not complete border.

joedf wrote:+1 #5 but I think I could Make the keys look better than in the image, I might submit a pull request... We'll see...

Agree. The keys can look much better.

joedf wrote:+1 #5 but I think I could Make the keys look better than in the image, I might submit a pull request... We'll see...

5 is just crappy single-tone css borders. You could improve on that by simply making the color use rgba(99,99,99,0.5) or the like. (for the quickest one). Others would probably require another html layer (or 2) around the section.

vasili111 wrote:

lexikos wrote:You seem to be describing (and in at least one case showing a screenshot of) the old documentation.

The documentation is from here: http://ahkscript.org/docs/AutoHotkey.htm

You misunderstand me. Oh well.

lexikos wrote:

vasili111 wrote:

lexikos wrote:You seem to be describing (and in at least one case showing a screenshot of) the old documentation.

The documentation is from here: http://ahkscript.org/docs/AutoHotkey.htm

You misunderstand me. Oh well.

I understand you now. You mean that I am describing in my proposal old style of documentation. There are thing that I think is better in old version of documentation. I think that old style is more ergonomic, easy to read, less pressure on eyes. But I think it need some improvements. I also cant say that I completely disagree with the improvement of the documentation. There are many things that I like more in new documentation. My post was about what can be done better in my opinion for improving documentation.

#5 could just use inline code as well, i think thats pretty much standard for describing keypresses

alternatively you could look into the <kbd> tag that StackOverflow/GitHub uses in its markdwon

The kbd from stackoverflow is exactly what I was thinking of.

The css for kbd