jmeter-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: Documentation and more
Date Tue, 06 Oct 2015 08:36:50 GMT
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.

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

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

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

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

>>
>>> 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?
>
>
> Regards,
>  Felix
>
>>
>>> What do you think?
>>>
>>> Regards,
>>>   Felix
>>>
>>>
>>>
>

Mime
View raw message