Hi all,
I have spend a lot of time lately going through the docs for jmeter and
especially looking at the markup side of the documentation.
I have noticed a few things, that could be (hopefully) improved.
Code examples
---------------------
The code examples are all treated as plain text. There is no further
markup to differentiate a shell script from an xml fragment or a java
source code example.
Maybe we could use a javascript library like
https://github.com/google/code-prettify? We would have to add an
language attribute to each of our source code examples and extend the
style sheets.
Layout of Menu-paths and key combos
---------------------------------------------------
Paths through menu like structures and combination of keys are text
only. I propose to add markup (like in docbook) for this.
Notes
--------
Notes can be used for different use cases like warnings or infos. I
think it would be nice to have an attribute on those notes to make them
distinguishable. The style of the note could reflect that attribute.
Icons with fonts
---------------------
Fonts like https://fortawesome.github.io/Font-Awesome/ provide nice
looking symbols, that scale well. Should we include such a font and use
the symbols for notes, bugs, ...? Would it be a problem, if the font had
a non apache license?
PDF files
-----------
There are a few pdf files linked on the web page. Should we convert them
to xml? I don't think we would really loose anything. On the other hand
the xml->html files would be better searchable by search sites. We
could link to the original pdf files, if we want to keep them.
Usage of the different style sheets
----------------------------------------------
The web page and the "printable" pages are generated by different style
sheets. As far as I can see, the "printable" pages are used by jmeter's
internal doc system. Is there any other usage for those pages?
If not, we could strip the number of generated "printable" files
further, since I haven't seen a way to show any page except the
usermanual/component_reference and usermanual/functions pages.
The web pages should be printable with the latest additions in trunk (at
least on firefox and chrome).
What do you think?
Regards,
Felix
