jmeter-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Felix Schumacher <felix.schumac...@internetallee.de>
Subject Re: Documentation and more
Date Wed, 11 Nov 2015 16:09:06 GMT
Am 10.10.2015 um 14:46 schrieb sebb:
> On 10 October 2015 at 13:29, Felix Schumacher
> <felix.schumacher@internetallee.de> wrote:
>> Am 10.10.2015 um 14:18 schrieb sebb:
>>> The printable docs serve several purposes:
>>>
>>> - help pages for use in JMeter itself.
>>> [It only uses component_reference.html and functions.html.]
>>> The display uses the built-in Swing components, and only supports
>>> links within the current page.
>>> I think that is an advantage, as the user cannot get lost, and there
>>> is no chance that the code will have to cope with arbitrary HTML.
>>> It is important that only the relevant information is displayed, so
>>> unnecessary items such as side menus should not be present.
>> Right. I think it useful too, that the user can't get lost. And since the
>> user should not leave the page, the menu is not useful there.
>>
>>> - offline browsing of all the JMeter user documentation.
>>> The side menus are not useful in this case.
>>> The links to online resources won't work, and the internal links from
>>> the side menu are made available from the main page.
>>> Having no side menu leaves more room for useful content.
>> Screens get really wide today, so a menu at the side might be helpful in
>> such a case, but generally I think you are right, that not all resources
>> should be linked in the offline pages.
> A wide screen means I can have the doc side by side with JMeter, plus
> some other info.
> The menu just wastes space.
> Besides, screens are also getting smaller (notepad etc).
If you scale the browser window, the menu on the side will change to a 
menu on the top, so you can still view the doc side by side.

But to cut it short, I think we will likely have to use two versions of 
docs. One for online viewing and one for offline viewing.

The sad thing is, that if we use the same version for offline viewing 
and jmeter help, we are bound to use the ancient version of html used 
for the java internal help viewer.

Don't really know what to do with that.
>
>>> - printing manual pages.
>>> The side menu is not useful here; it just wastes paper. Likewise the
>>> online only bits of the title banner.
>>> It should be possible to download the JMeter release and have
>>> everything needed to use it offline.
>> If you look at the printed pages (in firefox there is a print preview), you
>> will see, that there are no banners, menus and even no footer (while I think
>> the footer could be useful).
> Yes, with trunk the generated pages have much better printable representations.
> However that does not help with offline usage.
>
>> Are there any points you know, that a online connection is needed for the
>> online docs? (The fonts should fall back to local ones)
> Links to online resources obviously don't work.
>
>>>
>>> It would be useful to be able to print pages direct from the internet
>>> without the menus, but that is a separate issue.
>> That is possible right now with current trunk.
> Might be nice to add this to the current online docs if it is easy to
> do (e.g. just CSS changes).
That should be possible by backporting the @media print block at the end 
of new-style.css.

Should I do that?

Regards,
  Felix
>
>> Regards,
>>   Felix
>>
>>>
>>> On 10 October 2015 at 12:41, Felix Schumacher
>>> <felix.schumacher@internetallee.de> wrote:
>>>> Am 06.10.2015 um 10:36 schrieb sebb:
>>>>> On 5 October 2015 at 21:12, Felix Schumacher
>>>>> <felix.schumacher@internetallee.de> wrote:
>>>>>> Am 05.10.2015 um 17:18 schrieb sebb:
>>>>>>> On 4 October 2015 at 15:48, Felix Schumacher
>>>>>>> <felix.schumacher@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
>>>>>>>>
>>>>>>>>
>>>>>>>>


Mime
View raw message