Mailing-List: contact dev-help@jmeter.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@jmeter.apache.org
Subject: Re: Documentation and more
To: dev@jmeter.apache.org
References: <56113C57.3070503@internetallee.de>
 <CAOGo0VbWav5=QFeCtvUUTOc_Dk+cvD8-6hZ6_52h5iY2QYONMw@mail.gmail.com>
 <5612D999.7060506@internetallee.de>
 <CAOGo0VauNGd7O39=t1ZjBDN31CHKhr4uQNbbMtr1zk4pSGYmWw@mail.gmail.com>
 <5618F974.9030002@internetallee.de>
 <CAOGo0VZS8tQgBJ4LPO_sGj=6B_WriADEBM_Cks6F=bQ97oaVzw@mail.gmail.com>
From: Felix Schumacher <felix.schumacher@internetallee.de>
Message-ID: <56190492.1000600@internetallee.de>
Date: Sat, 10 Oct 2015 14:29:06 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.3.0
MIME-Version: 1.0
In-Reply-To: 
 <CAOGo0VZS8tQgBJ4LPO_sGj=6B_WriADEBM_Cks6F=bQ97oaVzw@mail.gmail.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit

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.

>
> - 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).

Are there any points you know, that a online connection is needed for 
the online docs? (The fonts should fall back to local ones)
>
> 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.

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
>>>>>>
>>>>>>
>>>>>>