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.
_______________________________________________
Mailing list: https://launchpad.net/~maria-docs
Post to : [email protected]
Unsubscribe : https://launchpad.net/~maria-docs
More help : https://help.launchpad.net/ListHelp
