Am 04.10.2015 um 19:44 schrieb Philippe Mouawad:
On Sunday, October 4, 2015, Felix Schumacher <
felix.schumac...@internetallee.de> wrote:
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.
+1
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.
+1
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.
+1
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?
possibly as doc is distributed as part of project
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.
+1, having them in pdf makes it harder to update the docs, at least in my
experience
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?
Not as far as I know.
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?
Maybe it would even be better in jmeter to open directly the web docs in
browser as we do it for templates instead of having a swing component for
it.
I think this is a rather big change and should be discussed separately.
(Not that I am against it, but I have no idea how much work this would
be and what consequences this would have.)
Regards,
Felix
Regards,
Felix
