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@avoinelama.fi> wrote:
On Fri, Aug 14, 2009 at 10:30 AM, Kristian Nielsen<knielsen@knielsen-hq.org> wrote:
Henrik Ingo <henrik.ingo@avoinelama.fi> 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@avoinelama.fi tel: +358-40-5697354 www: www.avoinelama.fi/~hingo book: www.openlife.cc
_______________________________________________ Mailing list: https://launchpad.net/~maria-developers Post to : maria-developers@lists.launchpad.net Unsubscribe : https://launchpad.net/~maria-developers More help : https://help.launchpad.net/ListHelp