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