List added. Some statistics may need expanding on, but most of the list is complete.

New formatting finished, should be complete with recommendations and missing statistics.

I think it looks better. One think I've noticed is that it seems that asciidoctor has problem with heading definition while using multiple characters (i.e. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^@) and recommends using @= (times the level of the heading, i.e. @== title level 2@) for headings, and because of that headings of the statistics names seems to be un-formatted.

I saw a few errors in docs, they should be fixed now.

Most of documentation structure has older headlines, I'd like it to be consistent, however it could cut down on file sizes. I'll make a project note to convert documentation to new style formatting.

I think we can safely make an on-going transition - all new or edited docs would be cleaned / corrected so it would be possible to correct the heading.

Right now they are not very readable, vide Screenshot 2016-04-22 11.04.24.png

It looks as if ASCIIDOC does not really use level 4 or lower headings as actual headings, hence the unreadability. I'll separate the description to another file and use higher level headings, hopefully that will fix the issues we are seeing.

It looks like it does use it, but translates it to Hx tags in HTML, and below some point it's display doesn't differ that much, i.e.:

<h5 class="title"><a name="_add_script_last_interval"></a>add-script last {interval}</h5>

Looks like I'll have to keep in mind to keep headings above level 5 in the final documents, because each document is nested, I'm limited to 4 levels before h5 is used and like you said it's indistinguishable from normal text.

%wojtek please have a look at current docs, everything should be more identifiable now, I'm still not too crazy about how the headings seem smaller than normal text, but this is about the best we can do unless we decide to remove the level 2/(3 in final document) headings for components.

I think it looks better now - thank you.

I'm still not too crazy about how the headings seem smaller than normal text, but this is about the best we can do unless we decide to remove the level 2/(3 in final document) headings for components.

Well, we could take the plunge and tweak a bit the CSS of our docs (tho, it will only apply to current html5 output, chunked html is generated via docbook until support for it will finally arrive in asciidoctor, which should probably happen in next version) and change sizes / formatting of the heading to make them more prominent.

For now I'll close this issue and we'll revisit this in the future, I'd rather all versions of documentation be along the same lines. It'll do for now, but I'll make another task to investigate these options.