[Maria-developers] Documentation for new features in MariaDB
We are starting to add new features to MariaDB (that are not in MySQL), including user-visible features. I think we need to decide now how we will handle keeping documentation for these new features. There is an open issue about the MySQL documentation being non-free, and whether we can do anything about it. But until this is resolved, on way or the other, we still need somewhere to write documentation. I think it is mainly about setting up a repository somewhere and start adding text. The important thing now is to get the content there, the presentation can be enhanced later. So we would have a manual "differences between MariaDB and MySQL" or something. If we have the content we can use it later in whatever form we need, if we omit adding the content now it is going to be really hard to figure out everything that's missing in a year or two. Daniel, any suggestions for what format to use? Can we use the same format as the MySQL documentation (is it docbook or something, can't remember)? Also, until we get procedures like at MySQL/Sun for a documentation team that ensures all features and bug fixes get documented, I think it is the responsibility of each developer that documentation gets added in the right place. I would really like to see us keeping the up the standard that everything in MySQL (now MariaDB) is documented. - Kristian.
Kristian Nielsen пишет:
We are starting to add new features to MariaDB (that are not in MySQL), including user-visible features. [skip]
Also, until we get procedures like at MySQL/Sun for a documentation team that ensures all features and bug fixes get documented, I think it is the responsibility of each developer that documentation gets added in the right place. I would really like to see us keeping the up the standard that everything in MySQL (now MariaDB) is documented.
If format is simple we can do it as were doing in early MySQL - every developer adds description to the doc then editor fix what he things is better. This of course require: 1) repository 2) initial text and structure of the document(s) 3) examples (if 2 is not self descriptive)
"Oleksandr \"Sanja\" Byelkin" <sanja@askmonty.org> writes:
If format is simple we can do it as were doing in early MySQL - every developer adds description to the doc then editor fix what he things is better. This of course require:
Yes, that is what I have in mind as well. And actually, I see no reason for now to put documentation in a separate repository (and several reasons not to). So I suggest to just write new documentation in Docs/mariadb.txt. I'm happy to try Creole as Daniel suggested. Though it would be good if there was an easy way to display the result of formatting the text (for the developer writing the documentation). - Kristian.
On Thu, Aug 13, 2009 at 10:15 AM, Kristian Nielsen<knielsen@knielsen-hq.org> wrote:
And actually, I see no reason for now to put documentation in a separate repository (and several reasons not to). So I suggest to just write new documentation in Docs/mariadb.txt.
I'm happy to try Creole as Daniel suggested. Though it would be good if there was an easy way to display the result of formatting the text (for the developer writing the documentation).
If you start writing the docs in a wiki markup, then the natural question is, why not use a subsection of AskMonty.org as "the repository". You would then have it automatically validated and formatted when pressing Submit button. (I'm not sure if there are big differences in MediaWiki and Creole?) Doing it in a wiki might in the future invite some authors who are MariaDB users, good at writing, but not developers, so may not have launchpad accounts or even bzr installed on their machines. What do we think? henrik -- email: henrik.ingo@avoinelama.fi tel: +358-40-5697354 www: www.avoinelama.fi/~hingo book: www.openlife.cc
Hi! Henrik Ingo пишет:
On Thu, Aug 13, 2009 at 10:15 AM, Kristian Nielsen<knielsen@knielsen-hq.org> wrote:
And actually, I see no reason for now to put documentation in a separate repository (and several reasons not to). So I suggest to just write new documentation in Docs/mariadb.txt.
I'm happy to try Creole as Daniel suggested. Though it would be good if there was an easy way to display the result of formatting the text (for the developer writing the documentation).
If you start writing the docs in a wiki markup,
I see one problem with Wiki-like markups - they are not designed to get result as hard copy (book/brochure) IMHO it is big disadvantage, some people like to read something material or at least PDF :)
On Thu, 13 Aug 2009 11:17:08 +0300, "Oleksandr \"Sanja\" Byelkin" <sanja@askmonty.org> wrote: <cut> Oleksandr> I see one problem with Wiki-like markups - they are not Oleksandr> designed to get result as hard copy (book/brochure) IMHO it Oleksandr> is big disadvantage, some people like to read something Oleksandr> material or at least PDF :) The reason I like creole markup is because it is easy to pick up and lowers the barriers to entry for potential contributors. The other reason for liking creole (and why we will not be using a wiki platform like mediawiki for our online docs) is that we can take one of the existing creole parsers (or write our own) and embed it into anything we want. Creole is not a wiki, it is simply an easy-to-use markup language which several wikis use. We aren't yet at a stage where we've even begun to make plans for what to do on the subject of printed documentation. However, after putting on my speculation hat, I can say this: creole markup has a logical structure, and it is possible to create something which translates creole-formatted documents into something which eventually results in a pdf suitable for printing. -- Daniel Bartholomew
Henrik Ingo <henrik.ingo@avoinelama.fi> writes:
If you start writing the docs in a wiki markup, then the natural question is, why not use a subsection of AskMonty.org as "the repository". You would then have it automatically validated and
Yes. In this case, we need to do more careful work, as then the documentation needs to state exactly which versions of MariaDB has which behaviour (as we can no longer easily associate a revision of MariaDB with a revision of the documentation). This is in any case a good thing to have, of course, but requires a bit more work and care. - Kristian.
On Thu, 13 Aug 2009 10:57:42 +0300, Henrik Ingo <henrik.ingo@avoinelama.fi> wrote: <cut> Henrik> If you start writing the docs in a wiki markup, then the natural Henrik> question is, why not use a subsection of AskMonty.org as "the Henrik> repository". You would then have it automatically validated and Henrik> formatted when pressing Submit button. (I'm not sure if there Henrik> are big differences in MediaWiki and Creole?) There are differences, but they aren't huge (for example: headings and lists are the same, bold and italics are different). There will need to be markup changes made when moving content from mediawiki to creole, but nothing that a script couldn't handle. Henrik> Doing it in a wiki might in the future invite some authors who Henrik> are MariaDB users, good at writing, but not developers, so may Henrik> not have launchpad accounts or even bzr installed on their Henrik> machines. Henrik> Henrik> What do we think? I think this is fine. -- Daniel Bartholomew
On Thu, 13 Aug 2009 09:15:06 +0200, Kristian Nielsen <knielsen@knielsen-hq.org> wrote: <cut> Kristian> I'm happy to try Creole as Daniel suggested. Though it would Kristian> be good if there was an easy way to display the result of Kristian> formatting the text (for the developer writing the Kristian> documentation). Bryan created a markup tester: http://askmonty.org/buildbot/reports/test_markup.php It's simple, but it does let you view the creole => html translation of your markup. -- Daniel Bartholomew
Daniel Bartholomew пишет:
On Thu, 13 Aug 2009 09:15:06 +0200, Kristian Nielsen <knielsen@knielsen-hq.org> wrote:
<cut>
Kristian> I'm happy to try Creole as Daniel suggested. Though it would Kristian> be good if there was an easy way to display the result of Kristian> formatting the text (for the developer writing the Kristian> documentation).
Bryan created a markup tester: http://askmonty.org/buildbot/reports/test_markup.php
It's simple, but it does let you view the creole => html translation of your markup.
It do not understand UTF-8 - it is really bad.
On Thu, 13 Aug 2009 14:44:29 +0300, "Oleksandr \"Sanja\" Byelkin" <sanja@askmonty.org> wrote: Daniel> http://askmonty.org/buildbot/reports/test_markup.php Daniel> It's simple, but it does let you view the creole => html Daniel> translation of your markup. Oleksandr> It do not understand UTF-8 - it is really bad. I disagree with saying "it is really bad" because it doesn't understand UTF-8. Yes, the final system should definitely understand UTF-8, but this isn't a final system, or even a prototype. It is just a *simple* page for testing/previewing bits of creole-formatted content, and as such it works well-enough to get the job done. -- Daniel Bartholomew
Daniel Bartholomew пишет:
On Thu, 13 Aug 2009 14:44:29 +0300, "Oleksandr \"Sanja\" Byelkin" <sanja@askmonty.org> wrote:
Daniel> http://askmonty.org/buildbot/reports/test_markup.php
Daniel> It's simple, but it does let you view the creole => html Daniel> translation of your markup.
Oleksandr> It do not understand UTF-8 - it is really bad.
I disagree with saying "it is really bad" because it doesn't understand UTF-8.
Yes, the final system should definitely understand UTF-8, but this isn't a final system, or even a prototype. It is just a *simple* page for testing/previewing bits of creole-formatted content, and as such it works well-enough to get the job done.
Then I can't understand why we should: 1) build a new system 2) With pure printing abilities instead of picking up something already used for documentation and which converted to many formats? I was pretty satisfied with old MySQL system (forgot what it was but it generate a lot of formats), docbook also looks good enough.
Hi, Oleksandr "Sanja" Byelkin wrote:
Daniel Bartholomew пишет:
On Thu, 13 Aug 2009 14:44:29 +0300, "Oleksandr \"Sanja\" Byelkin" <sanja@askmonty.org> wrote:
Daniel> http://askmonty.org/buildbot/reports/test_markup.php
Daniel> It's simple, but it does let you view the creole => html Daniel> translation of your markup.
Oleksandr> It do not understand UTF-8 - it is really bad.
It understands UTF-8 now.
I disagree with saying "it is really bad" because it doesn't understand UTF-8.
Yes, the final system should definitely understand UTF-8, but this isn't a final system, or even a prototype. It is just a *simple* page for testing/previewing bits of creole-formatted content, and as such it works well-enough to get the job done.
Then I can't understand why we should:
1) build a new system 2) With pure printing abilities
instead of picking up something already used for documentation and which converted to many formats?
I was pretty satisfied with old MySQL system (forgot what it was but it generate a lot of formats), docbook also looks good enough.
We aren't creating a system for a plain manual, we are creating a knowledge base so the community can help us generate content and ask questions. This KB can be used for our manual as well. If we ever want a more formal manual, we can adopt the content of the KB into docbook, I think that is what MySQL still uses. I guess I should do a presentation in Majorca about this. -- Bryan Alsdorf, Lead Web Developer Monty Program, AB. http://askmonty.org
On Thu, Aug 13, 2009 at 10:31 PM, Bryan Alsdorf<bryan@askmonty.org> wrote:
We aren't creating a system for a plain manual, we are creating a knowledge base so the community can help us generate content and ask questions. This KB can be used for our manual as well. If we ever want a more formal manual, we can adopt the content of the KB into docbook, I think that is what MySQL still uses.
Actually, we will need to end up with something that looks like a manual. A knowledgebase/wiki co-edited with many community members is a good way to get there. But Kristian's original point is an important one too. As we develop new features into MariaDB, we should document those just as one would have done for the MySQL manual. This should be part of the development process. If you don't document them there, they aren't documented anywhere, and no community member can later document it except for reading the code itself. 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?)
I guess I should do a presentation in Majorca about this.
Very good idea. I could actually give you from 30 to 60 minutes on Saturday as a scheduled presentation (not unconference). henrik -- email: henrik.ingo@avoinelama.fi tel: +358-40-5697354 www: www.avoinelama.fi/~hingo book: www.openlife.cc
Henrik Ingo wrote:
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?)
According to this, yes docbook. http://dev.mysql.com/doc/mysqldoc-guide/en/mysqldoc-guide-overview.html
I guess I should do a presentation in Majorca about this.
Very good idea. I could actually give you from 30 to 60 minutes on Saturday as a scheduled presentation (not unconference).
30 minutes should be more then enough, unless people have a lot of questions. -- Bryan Alsdorf, Lead Web Developer Monty Program, AB. http://askmonty.org
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? - Kristian.
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
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
Note: I strive to post a summary of MariaDB things discussed at MP company meeting last week. Knowing more about the vision for the askmonty.org knowledgebase, I thought picking up this thread is appropriate: On Sun, Aug 16, 2009 at 8:04 PM, Henrik Ingo<henrik.ingo@avoinelama.fi> wrote:
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.
...to summarize what (relevant to this) was said about the knowledgebase (still in development), Monty's and Bryan's vision is for it to be - a collection of Question + Answer articles on MariaDB, but extendable to articles in general. - it is not *one* book, many entry points, many "table of contents". Bryan calls this a "forest". - can function as a reference manual: there are articles that describe MariaDB functionality as detailed as a reference manual does, and these can be collected into table of contents separately for MariaDB 5.1, 5.2... The knowledgebase will be used Creole markup. I believe Daniel already that Mediawiki markup is an ok interim solution. It seems to me if KB is the ultimate goal, then starting to write the reference manual on askmonty.org wiki is a good start. For now, we should aim at documenting the new features we produce, both as release notes and as an incomplete reference manual (complete when read as an addon to MySQL manual). henrik -- email: henrik.ingo@avoinelama.fi tel: +358-40-5697354 www: www.avoinelama.fi/~hingo book: www.openlife.cc
On Wed, 26 Aug 2009 15:28:49 +0300, Henrik Ingo <henrik.ingo@avoinelama.fi> wrote: <cut> Henrik> The knowledgebase will be used Creole markup. I believe Daniel Henrik> already that Mediawiki markup is an ok interim solution. Yes, mediawiki markup is close enough to Creole to be a good interim format. Henrik> It seems to me if KB is the ultimate goal, then starting to Henrik> write the reference manual on askmonty.org wiki is a good start. Henrik> Henrik> For now, we should aim at documenting the new features we Henrik> produce, both as release notes and as an incomplete reference Henrik> manual (complete when read as an addon to MySQL manual). To facilitate this I have created a MariaDB 5.1 reference manual on the wiki. The table-of-contents can be found here: http://askmonty.org/wiki/index.php/Manual:Contents There is also an index, which can be found here: http://askmonty.org/wiki/index.php/Category:MariaDB_5.1_Reference_Manual (Note: The index is just a page index, not a function or keyword index. The index exists so you can locate pages alphabetically, the TOC exists so you can locate pages logically. Of course, right now there are so few pages that the distinction is practically meaningless, but hopefully that will change. :) ) As Henrik states, the purpose of this *incomplete* reference manual is to document the *differences* between MariaDB 5.1 and MySQL 5.1. Do not think of it as a complete reference manual. To bootstrap it I have added a few things from the "MariaDB versus MySQL" and "MariaDB 5.1 TODO" pages of the wiki: http://askmonty.org/wiki/index.php/MariaDB_versus_MySQL http://askmonty.org/wiki/index.php/MariaDB_5.1_TODO Please add any entries to the TOC which you think should be in the manual and feel free to reorganize the TOC if you feel there's a better or more logical way to do it. Also, if there's anything I've added which should *not* be there, let me know so I can remove it. I've created a help page with instructions on the preferred way to add things here: http://askmonty.org/wiki/index.php/Help:Adding_Pages_to_Categories Thanks. -- Daniel Bartholomew
On Fri, Sep 4, 2009 at 10:31 PM, Daniel Bartholomew<dbart@askmonty.org> wrote:
Henrik> For now, we should aim at documenting the new features we Henrik> produce, both as release notes and as an incomplete reference Henrik> manual (complete when read as an addon to MySQL manual).
To facilitate this I have created a MariaDB 5.1 reference manual on the wiki. The table-of-contents can be found here: http://askmonty.org/wiki/index.php/Manual:Contents
There is also an index, which can be found here: http://askmonty.org/wiki/index.php/Category:MariaDB_5.1_Reference_Manual
Hi Daniel Thanks for picking this up! It is good to have some form of Manual in place when we start making releases now.
As Henrik states, the purpose of this *incomplete* reference manual is to document the *differences* between MariaDB 5.1 and MySQL 5.1. Do not think of it as a complete reference manual.
This is the goal yes. That being said... If a volunteer wants to write Manual articles on any topic outside this goal, there is nothing we can do to stop you :-)
To bootstrap it I have added a few things from the "MariaDB versus MySQL" and "MariaDB 5.1 TODO" pages of the wiki:
http://askmonty.org/wiki/index.php/MariaDB_versus_MySQL http://askmonty.org/wiki/index.php/MariaDB_5.1_TODO
Please add any entries to the TOC which you think should be in the manual and feel free to reorganize the TOC if you feel there's a better or more logical way to do it. Also, if there's anything I've added which should *not* be there, let me know so I can remove it.
Daniel, one more piece of content that you could move into the manual is that currently on the download page there is something that looks like installation instructions. I would like these to be removed from the download page so it is just a clean page of download links, and the Manual is an excellent place to move that text to! (Then link to it from the download page.) henrik -- email: henrik.ingo@avoinelama.fi tel: +358-40-5697354 www: www.avoinelama.fi/~hingo book: www.openlife.cc
On Wed, 12 Aug 2009 15:27:59 +0200, Kristian Nielsen <knielsen@knielsen-hq.org> wrote: Kristian> We are starting to add new features to MariaDB (that are not Kristian> in MySQL), including user-visible features. Kristian> Kristian> I think we need to decide now how we will handle keeping Kristian> documentation for these new features. Kristian> Kristian> There is an open issue about the MySQL documentation being Kristian> non-free, and whether we can do anything about it. But until Kristian> this is resolved, on way or the other, we still need Kristian> somewhere to write documentation. Kristian> Kristian> I think it is mainly about setting up a repository somewhere Kristian> and start adding text. The important thing now is to get the Kristian> content there, the presentation can be enhanced later. So we Kristian> would have a manual "differences between MariaDB and MySQL" Kristian> or something. If we have the content we can use it later in Kristian> whatever form we need, if we omit adding the content now it Kristian> is going to be really hard to figure out everything that's Kristian> missing in a year or two. Kristian> Kristian> Daniel, any suggestions for what format to use? Can we use Kristian> the same format as the MySQL documentation (is it docbook or Kristian> something, can't remember)? The Knowledgebase documentation will use Creole markup, so that is what I prefer. Creole is similar to MediaWiki/MoinMoin/wiki markup. There is a cheat sheet on the markup available here: http://wikicreole.org/wiki/CheatSheet However, like you said, the important thing is to get content written now, so if you are more comfortable and more productive using a different markup (docbook, html, plain text, etc...), use it and I'll worry about converting it into Creole for the Knowledgebase. On the question of where to put the documentation . . . if we want a shared repository for it, Launchpad is probably the natural place. Kristian> Also, until we get procedures like at MySQL/Sun for a Kristian> documentation team that ensures all features and bug fixes Kristian> get documented, I think it is the responsibility of each Kristian> developer that documentation gets added in the right place. I Kristian> would really like to see us keeping the up the standard that Kristian> everything in MySQL (now MariaDB) is documented. I agree. Thanks. -- Daniel Bartholomew
On Wed, Aug 12, 2009 at 9:27 AM, Kristian Nielsen<knielsen@knielsen-hq.org> wrote:
We are starting to add new features to MariaDB (that are not in MySQL), including user-visible features.
I think we need to decide now how we will handle keeping documentation for these new features.
There is an open issue about the MySQL documentation being non-free, and whether we can do anything about it. But until this is resolved, on way or the other, we still need somewhere to write documentation.
I just add one thing to the discussion, and say: look at how the InnoDB plugin is documented. http://www.innodb.com/doc/innodb_plugin-1.0/index.html It's an example of well written documentation. Morgan
participants (7)
-
Bryan Alsdorf -
Daniel Bartholomew -
Henrik Ingo -
Kristian Nielsen -
Morgan Tocker -
Oleksandr "Sanja" Byelkin -
Robert Hodges