maria-docs team mailing list archive

[Ian Gilfillan <ian@xxxxxxxxxxx>]

I agree, this has been bugging me a while, but I haven't been sure about 
the best way to approach it.

If I understand your suggestion, there'd be, in your example, a 5.5 
version of the page, a 10.0 version, a 10.1 version and a generic 
version, with all content being generated automatically from product 
macros used on the generic version.

The existence of a generic version solves one problem with the solution 
used by MySQL, where link placed on outside sites has to be to a 
specific version and often becomes stale (for example pointing to the 
5.0 version years later when it would make more sense to point to the 
current version).

The product checkboxes on the left are a current attempt towards this, 
though they're not ideal. I don't think many people know they exist, 
they only grey out the content, and they don't maintain state.

The main problem is that the product macros in their current form don't 
take care of the syntax issue you mentioned. The syntax section cannot 
really be broken up by the macros and so has to only show one version of 
the syntax, ideally the most recent. So there's no easy way to 
automatically generate a version-specific version of the syntax.

If there were more flexible macros, something like this would work.

To implement this would then require:

- add a new kind of <product> macro that does not display any extra 
text, but is only used for hiding/displaying based on version. This 
would be used particularly in the syntax area.
- drop the product checkboxes, and replace with switches right next to 
the article header (or somewhere equally prominent). These switches 
display major versions (not minor, as currently), and by clicking the 
appropriate version, text marked in the product macros will 
appear/disappear (not just be greyed). The switches shown depend on the 
context. If the article has no product templates, then none are 
clickable, and all major versions are highlighted. If a feature is 
available or not available for a major version, the switches adjust as 
required. By default, all content would be displayed.

Thanks for the inspiration - I'll follow this up and see what needs to 
be done to implement something like this in the Knowledge Base.

ian


On 01/14/2015 06:29 PM, Jean Weisbuch wrote:
> As 10.1 is on its way and has new features of its own and some others 
> got deprecated, its getting a bit "complex" on some KB pages to have 
> documentation for multiple major versions (eg. 5.1, 5.2, 5.3, 5.5, 
> 10.0, 10.1, ...) on one page along with minor versions specifics (when 
> changes got introduced after the first released version).
>
> A simple example (not the best one but its the page i was reading at 
> the moment) : the SELECT statements documentation 
> (https://mariadb.com/kb/en/mariadb/documentation/sql-structure-and-commands/sql-commands/data-manipulation/select/).
> The first part of the documentation is about the syntax but it only 
> shows the 5.5 GA syntax, features added later must be found manually 
> on the page and syntaxes deprecated after the 5.5 GA will have to be 
> found manually too.
>
> It would be interesting to have the possibility to use a "generate per 
> major release" flag on KB pages that would automatically generate 
> subpages that are major-version specific with a switch between major 
> release pages like on the MySQL documentation.
>
> For example, if a <<product mariadb from=10.0 to=10.0>> macro would be 
> used (only using a major release version number or maybe by adding a 
> "specific" flag to the macro to avoid mistakes), there would 
> automatically be a 5.5 and a 10.0, 10.1 subpages (specified, previous 
> and next releases) created where the content of the tag would only be 
> shown on the 10.0 page (and on the "generic" page that shows every 
> release infos such as its done at the moment).
>
> With that kind of automatic generation, it would be simpler to keep up 
> to date documentation for every major release without having to create 
> a specific page per major release or to display multiple <<product>> 
> macros on one page while keeping it simple to manage (especially as 
> there are also the translations to keep up).
>
> Having the possibility to set a from/to product version for a whole KB 
> page could also be interesting to keep the browsing of the KB pages 
> lighter if the user selected a specific MariaDB release, it could also 
> be used to put automatically the info on top of the KB page in a clean 
> way (example of how it is done actually : 
> https://mariadb.com/kb/en/mariadb/documentation/managing-mariadb/optimization-and-tuning/query-optimizations/aborting-statements-that-exceed-a-certain-time-to-execute/) 
> and it could be of use for automatically generated documentation from 
> the KB pages.
>
>
> These ideas are not perfect and i dont know if it would be simple to 
> implement these on the KB code but the need for a solution for the 
> problem will only keep growing.