Am 06.10.2015 um 10:36 schrieb sebb:
On 5 October 2015 at 21:12, Felix Schumacher
<felix.schumac...@internetallee.de> wrote:
Am 05.10.2015 um 17:18 schrieb sebb:
On 4 October 2015 at 15:48, 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.
For which many thanks.
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.
OK, so long as the JS library has a compatible license.
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.
Not sure I know what that means.
You can see an example at
http://people.apache.org/~fschumacher/jmeter/usermanual/doc-writers.html
I see.
Do you think we should include such markup?
And by the way, do you think such a page would be useful? And if so, where
should it be located?
We should document the tags that are being used.
It's a developer resource, and doesn't belong in the user manual.
We probably need to expand the online website to include more
developer-centric materials.
Any preference on the location? (Documentation, Community?)
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.
OK
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?
Potentially, yes it might be a problem.
Raise a LEGAL JIRA with specific proposals.
Will try to.
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.
There should be editable sources for the PDF files, e.g. in ODF format.
No need to convert to XML (which would likely be much harder to maintain).
It is not the editable source I am after. I think it is nicer to read on
browsers, that have no pdf reader embedded.
I see.
The documents seem to be pretty standard layout, so they should not loose
anything when converted to standard doc html. The maintainance is a point,
but a minor one in my eyes.
Will they still be printable?
They need to be usable off-line as well.
Have you tried to look at the print layout of the current trunk docs?
With the last changes they are at least as good as the printable version
(at least in my eyes and when printed with a modern browser :).
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?
Yes, they are used for off-line documentation.
We should not expect users to have to go online for the documentation.
I always looked at the documentation in the docs folder.
The standard binary dist only only includes the printable-docs folder.
(There are a few files under docs, but no html except under docs/api).
I expect you are looking at your development workspace.
You are right.
If the printable
one is the preferred one, we should look at the colors at least.
Fine to tweak the colours.
But it would be wrong to use the website for offline browsing; the two
serve different purposes.
I would like to get the stylesheets to get closer for those two
versions. Therefore I would like to get to a table less version, or even
use the same stylesheets with a parameterized run.
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.
We need to keep offline docs.
That's right. I think offline docs are really useful.
Which is what the printable-docs are intended for.
The web pages should be printable with the latest additions in trunk (at
least on firefox and chrome).
The website pages have menus that are not useful for offline browsing.
For me the question is, do they hurt so much, that we have to maintain two
versions of the docs?
And besides, the menu is not printed with the current version. Also, I
missed the menu while browsing the offline version.
Regards,
Felix
Regards,
Felix
What do you think?
Regards,
Felix