How to contribute to the MySQL Docs

How to contribute to the MySQL Docs


We had a great question from a reader yesterday:

Is there a todo/nice-to-have list anywhere for MySQL documentation? Or perhaps a list of Devs who require documentation support? Or is all documentation a function of the core Documentation team?

All documentation is handled by a team of five dedicated technical writers (of which I am one). Five sounds like a lot, but with 7000 pages of documentation across various versions of the manual (since we have separate manuals for the 4.1, 5.0 and 5.1 trees, not to mention the various other tools we also document) it's a lot of work :)

We have a list of work to be completed in various areas which is constantly being updated as new features are added to MySQL, the GUI tools and elsewhere, and are constantly in contact with the devs on ways to improve and extend the documentation. Individually each member of the Docs team is responsible for a specific part of the manual, and some projects are small (like minor changes to tables or layout) and some are larger (like my recent work to rewrite the Connectors chapter, which has so far taken a couple of months).

We also have the bugs system which contains the user driven bugs and requests for features and improvements, see below for more info.

For an idea of what goes on in the Docs team and what is involved in writing documentation at MySQL, you might want to check my FSM blog (also available through Planet MySQL) where I regularly post on the latest things happening in the Docs team and what goes on behind the scenes.

Where would one go to 'volunteer' to help with documentation?

We don't have a direct method to support this, in the same way that we don't have a direct way for people to provide patches into the MySQL code, only through contributions that are verified for inclusion. For the Docs this is to ensure that the documentation is correct, valid for the appropriate version of the software (or indeed all versions of the software), and is obviously correct in terms of interactions with other elements. On that last point, sometimes a change in one place in the documentation has a domino effect on others and it is not a simple case of changing one section of the documentation, but many.

We in the Docs team generally have the benefit of more exclusive access to the Devs which makes parts of this process sometimes easier, but not always :)

As a general rule:

If you have a specific bug or feature request then the place to suggest it is in the Bugs system at http://bugs.mysql.com. There are appropriate categories for Server, connector and other docs areas. This is the best place to mention anything that particularly bugs (no pun intended) you and that needs to be addressed. You'll generally get an initial response within a few days, and most problems are completed within a couple of weeks. This is also, obviously, a good place to find out whether the issue you have is already waiting to be addressed. You can include suggested text or content in the report if you wish, although for the reasons given above I can't guarantee that we'll use it verbatim.

If you want provide additional examples, help or tips then there are two avenues available. One is the comments system on the appropriate manual page. The other is to use the MySQL Forge to provide the information. This is generally the best place for material that goes beyond the scope of reference material and into the realm of examples and implementation details

Of course, you can always download the DocBook documentation that we create through the Subversion repository of that documentation through the Resources page. There's even a handy README in there to tell you what's what - I'll be producing a post on how to use this, the tools required and how to build your own docs in a forthcoming post.

Category: 

Comments

Anonymous visitor's picture
Submitted by Anonymous visitor (not verified) on

Hi there. I`m a young boy. I`m graduating informatic and wanted contribute of some way with the translation of the manual of MySQL to portuguese Brasil.

I don`t know how I can to make use for do it. Then I`m here asking you how.

My e-mail is marcos_804@yahoo.com.br

Thank you for helping me.

Anonymous visitor's picture
Submitted by Anonymous visitor (not verified) on

Hi Marcos,

we have a Portuguese translation of the MySQL Reference Manual on http://dev.mysql.com/doc/refman/4.1/pt/index.html, but it's quite old. It could need an update, but don't even think of trying this: The Manual has 2000 pages by now, which takes a full-time translator about half a year.

But what about translating the MySQL (GUI) Tools? Particularly MySQL Query Browser is very popular among developers, and it's fairly easy to localise. You may translate the user interface (so that the program "speaks" Portuguese), or the manual, or both.

Let me know if you'd like to try this! Send a mail to stefan@mysql.com. Thanks!

-Stefan

Author information

Martin Brown's picture

Biography

Martin “MC” Brown is a member of the documentation team at MySQL and freelance writer. He has worked with Microsoft as an Subject Matter Expert (SME), is a featured blogger for ComputerWorld, a founding member of AnswerSquad.com, Technical Director of Foodware.net and, and has written books on topics as diverse as Microsoft Certification, iMacs, and free software programming.