maria-developers team mailing list archive

[Robert Hodges <robert.hodges@xxxxxxxxxxxxxx>]

Hi everyone, 

We have gone through some of the same wiki vs. real doc thinking on Tungsten
that has come up here in the list.  Our conclusion was that you need to do
documentation properly right from the start.  This includes:

* Pick one technology and use it consistently.
* Ensure you can deal with open source vs. commercial issues from one source
copy
* Ensure you can deal with product versions
* Develop a stable build and publication process

In our case we use docbook, which I think is pretty good for a number of
reasons, not least of all it's very stable.  Our tech pubs guy Tommi
Takkunen-Lauri put together an excellent writing guide that makes editing
docbook trivial even for beginners.  I can provide a copy directly if
anybody is interested.

For MariaDB, I think two good principles would be:

1.) Assume the docs will be completely rewritten over a period of time.
There's no short cut.  Start writing your documentation now according to the
structure and technology you want in the end.

2.) Do not use the MySQL documentation structure as a model.  It has become
an impenetrable thicket.  Just as one example, the chapter on replication is
almost unreadable because there's an unclear division between wanting to
provide reference material and wanting to provide a task-oriented
description of replication setup.

In the short term, MariaDB perhaps should start with an
installation/configuration guide, and release notes.  The release notes
would contain a list of MariaDB extensions and/or differences.  This will
hold the line until you can document SQL syntax, system variables,
replication, etc., more fully.

My $0.02, Robert

On 8/16/09 10:04 AM PDT, "Henrik Ingo" <henrik.ingo@xxxxxxxxxxxxx> wrote:

> On Fri, Aug 14, 2009 at 10:30 AM, Kristian
> Nielsen<knielsen@xxxxxxxxxxxxxxx> wrote:
>> Henrik Ingo <henrik.ingo@xxxxxxxxxxxxx> writes:
>> 
>>> Now that I think about it, maybe this part of the documentation effort
>>> could for the time being be done as a diff against the MySQL manual.
>>> (Which is DocBook?)
>> 
>> Have you checked the implications of the copyright/license issues for this
>> idea?
> 
> So we couldn't touch the actual MySQL manual - and I don't know if a
> diff actually makes sense then. The diff itself I'm sure would turn
> out to be legal, otoh if it would be technically required to have a
> copy of the MySQL manual at hand just to write MariaDB
> documentation... Now that I think about it it sounds like a stupid
> arrangement anyway. (I still think it would be legal.)
> 
> Maybe calling it a "delta" is better, ie we would try to place things
> in the same chapters etc, but write our docs as an independent text,
> not a diff. Logically it is still like a "diff", in the sense that the
> reader is expected to first read the MySQL manual, then our additional
> documentation. Also the choice to use the same format as the "parent
> manual" would still make sense in this approach.
> 
> Just to make it clear: Over time we of course need to have a full
> independent manual of MariaDB, which can then be in any format and
> written with any tools our technical writers prefer.
> 
> henrik
> --
> email: henrik.ingo@xxxxxxxxxxxxx
> tel:   +358-40-5697354
> www:   www.avoinelama.fi/~hingo
> book:  www.openlife.cc
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~maria-developers
> Post to     : maria-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~maria-developers
> More help   : https://help.launchpad.net/ListHelp
>