Tuesday Nov 05, 2013

MySQL documentation writer for MEM and Replication wanted!

As MySQL is thriving and growing, we're looking for an experienced technical writer located in the UK or Ireland to join the MySQL documentation team.

For this job, we need the best and most dedicated people around. You will be part of a geographically distributed documentation team responsible for the technical documentation of all MySQL products. Team members are expected to work independently, requiring discipline and excellent time-management skills as well as the technical facilities and experience to communicate across the Internet.

Candidates should be prepared to work intensively with our engineers and support personnel. The overall team is highly distributed across different geographies and time zones. Our source format is DocBook XML. We're not just writing documentation, but also handling publication. This means you should be familiar with DocBook, and willing to learn our publication infrastructure.

Your areas of responsibility would initially be MySQL Enterprise Monitor, and MySQL Replication. This means you should be familiar with MySQL in general, and preferably also with the MySQL Enterprise offerings. A MySQL certification will be considered an advantage.

Other qualifications you should have:
  • Native English speaker
  • 5 or more years previous experience in writing software documentation
  • Familiarity with distributed working environments and versioning systems such as SVN
  • Comfortable with working on multiple operating systems, particularly Windows, Mac OS X, and Linux
  • Ability to administer own workstations and test environment
  • Excellent written and oral communication skills
  • Ability to provide (online) samples of your work, e.g. books or articles
If you're interested, contact me under stefan.hinz@oracle.com.

For reference, the job offer can be viewed here.

Thursday Feb 09, 2012

Linux Documentation Writer Wanted!

The Oracle Linux and Virtualization Documentation Team is seeking an experienced Technical Writer
with a focus on writing documentation for the Oracle Linux product. (The MySQL Documentation Team is part of that group as well.)

Applicants should be located in either Ireland, the UK, Sweden, Norway, Denmark, or Finland (click on the links for a detailed job description).

We're a vastly distributed team, with writers in Australia, North America, and Europe. Our infrastructure is based on DocBook XML, and we're not just writing docs, but also maintain the whole processing and publication work chain.

Key competencies you should have include:

  • 3 or more years previous experience in writing software documentation (please provide URLs of your writings I can look at!)
  • Experience with writing documentation for system level software and operating systems
  • Strong knowledge of the Linux operating system
  • Strong knowledge of XML, DocBook XML, and XSL style sheets (and motivation to help maintain and expand our tools and infrastructure)
  • Ability to administer own workstation and test environment
  • Good experience with distributed working environments and versioning systems such as SVN

If this sounds like something for you, follow the links above and send in your application!

Monday Sep 06, 2010

Farewell CHM, hello EPUB!

For a long time, the MySQL Documentation Team has been providing CHM files for most MySQL documentation we publish. Like many other formats, CHM-format docs can be downloaded from http://dev.mysql.com/doc. CHM (Compiled HTML Help) has been the de facto standard help file format on Windows since 1997, but the technology behind it is outdated and has all kinds of quirks. The successor format introduced with Windows Vista is AP Help, but it hasn't taken off in practice so far. So, with CHM being outdated and AP Help spread anything but widely, lots of vendors have started providing documentation on Windows in PDF or HTML format.

Building CHM-format documentation is a challenge of its own. I'll not go into details here, so let me just state that it requires a dedicated Windows box (or VM), and while it can be automated using Power Shell commands, there's no way to find out whether or not a CHM file was built correctly, except by manual inspection. This makes it different from all other documentation formats where technical QA is done (successfully) in an automated fashion.

With the increasing complexity and size of our documentation (the MySQL 5.1 Manual contains more than 1.6 million words now!), providing CHM has become more and more of a pain, because builds tend to break more often. We've stopped shipping CHM with the MySQL Server on Windows months ago because we simply couldn't guarantee that the help file shipped with the software would work. Also, we're running short on hardware resources, so we'd rather stop wasting the resources we have on building a format that's of limited use, anyway.

This is why we'll stop providing CHM for any of the documentation we publish.

To alleviate potential pains anyone might have with this decision, let me tell you that we've started providing EPUB-format docs. EPUB (see http://en.wikipedia.org/wiki/EPUB) is an open standard format for screen readers, mobile or not, and is fairly easy (and not resource-intensive!) to compile. Thanks to Lenz for suggesting to build EPUB!

Go to http://dev.mysql.com/doc to grab MySQL documentation in EPUB format. To read EPUB on desktop machines, I use a Firefox add-on, unsurprisingly called epubreader, which loads EPUB documents fast and renders them nicely. That said, please be aware that EPUB can't do anything about the fact that the MySQL Reference Manual is huge, so downloading it to a mobile device can take a while. The MySQL 5.1 Manual is currently a whopping 15 MB!

Monday Mar 23, 2009

Google Summer of Code: Help improve MySQL documentation!

MySQL is participating in Google Summer of Code 2009 (GSoC for short), and so is the MySQL documentation team. We've just put our ideas on this page; you might want to have a look if you're interested in applying for a GSoc project.

One of the projects is purely technical and doesn't involve writing any documentation, but rather improving the technique that goes on behind the scenery.

The other project does involve writing documentation, but it's mostly (if not exclusively) about creating examples for the Connectors & APIs chapter of the MySQL Reference Manual, so you don't have to be a Pulitzer award winner to contribute, but you should rather have a good amount of experience using MySQL through drivers and APIs.

Tuesday Mar 17, 2009

MySQL documentation available on docs.sun.com now

We're proud to announce that significant parts of the MySQL documentation are available on docs.sun.com now, including the MySQL 5.0 Manual, the MySQL 5.1 Manual, the MySQL 6.0 Manual, and the MySQL Enterprise Monitor documentation.

Big deal? Well, certainly for us, the MySQL Documentation Team. This marks a big step forward towards making MySQL visible as software offered by Sun Microsystems. The reason for publishing our documentation in two places (the MySQL Developer Zone and the Sun documentation home) is to make MySQL more visible and the docs easily accessible for Sun customers who are used to finding documentation in the "traditional" place on docs.sun.com.  At the same time, we were anxious not to break anything for MySQL users and customers who are used to their "traditional" site, the MySQL Developer Zone.

And, of course, we didn't want the documentation to deviate in those two places, so we had to find a way of synchronizing it in an automated fashion. Achieving this proved to be harder than anticipated. People tried to talk us into doing updates manually (no way!), and it took some time to find out how to do this using a command-line tool and crontab. Well, we're finally there, thanks to Martin "MC" Brown's fabulous work (he's even managed to blog about this faster than I). Thanks also to Sue Kober and Mimi Tam who explained the command-line publishing interface to us, and to Jeff Gardiner who pointed us to the right people to talk to!

The main resource for finding all MySQL documentation remains the documentation library on the MySQL Developer Zone,  though. You'll find all documentation handled by the MySQL Documentation Team there, including a great variety of formats for download. Also, the documentation on the MySQL Developer Zone has all the latest edits (it's updated multiple times each day), while the docs.sun.com  documentation is updated once per day (which is still good enough I believe).

Wednesday Nov 26, 2008

MySQL Enterprise Monitor documentation public now

The MySQL Enterprise Monitor continuously monitors MySQL servers and alerts to potential problems before they impact the system. It helps eliminating security vulnerabilities, improves replication, optimizes performance, and more. Its newest feature, Quan (Query Analyzer), helps identify queries that could be tuned to improve performance. Quan enables database administrators to do the work that would otherwise require hours in just minutes, or even seconds, and it provides ongoing statistical information about the performance of your queries.

MySQL Enterprise Monitor is a commercial offering by Sun Microsystems, and so was the documentation. To help anyone (even if they're not customers) get a better and complete understanding of what exactly MySQL Enterprise Monitor is about and what it can do, we've decided to make its full documentation publicly available. This has been done now, and the docs are part of the MySQL Manual now; see: http://dev.mysql.com/doc/refman/5.1/en/mem-introduction.html

The MySQL Enterprise Monitor documentation is also part of of the manuals that cover MySQL 5.0 and 6.0.


mysqlf is a common typo on the #docs IRC channel of the MySQL documentation team. It shows a high (some might say, dangerous) degree of identification with MySQL. Trying to pronounce it will probably result in tongue injuries.


« June 2016