documentation

Free books for free software

The shelves of my local bookstore are crammed with hundreds of computer titles, meters of space dedicated to titles such as, “Get Your MCSE In Three Days”, and, “Microsoft Exchange Explained”, and, “The Moron’s Guide To MS-Windows XP”.

I’ve noticed a dearth of free software titles. It’s a shame.

How usability inhibits good software

Have you ever founda new piece of software that sounds like it's the perfect match foryour needs, only to get bogged down by bad documentation or ahorrendous interface? Many people will quickly discardprograms out of frustration caused by avoidable usabilityissues. How can software developers avoid disenfranchisingpotential users?

Usability refers to how easy it isto use a product in order to achieve a goal. Measured inefficiency and elegance, software usability is affected by a number offactors; two of the biggest hurdles are the interface and documentation.

Interface

Extending documentation formats and facilities using the Docbook base

Back in July, we made an Eclipse documentation plug-in of the MySQL manuals available for users to download.

In truth, the Eclipse documentation format is actually just HTML; you have to combine the HTML with a plug-in manifest that details the documentation, version number etc so that the documentation is loaded and identified as a valid plug-in element when Eclipse is started.

Documentation formats

We were discussing documentation formats today within the team, and I have to admit that personally I don’t have a preferred format. I find I use the HTML (online) formats often when I'm looking for something specific, and the PDF when I want to read something in more detail. As I spend most of my day in emacs when programming, I use either HTML or the Info format.

Deep in the Docs

This week, and specifically today, marks a minor milestone in my employment at MySQL—I’m finally a full time employee, no longer on probation. It has also been probably the busiest week since I started at MySQL, except for the week spent at the developers’ conference in Sorrento.

Why so busy?

Because I’ve spent many hours deep in the build process that actually generates the documentation, partly to address some existing errors, but also to improve the documentation after some new content was added. In summary, the following major steps were made this week:

MySQL documentation update - week 24

Documentation is a vital part of any application, proprietary or free software, as it is often the first way to communicate with users about the application or software and how it should be used. I also think it tends to be one of the areas most taken for granted; most users expect it to be there and often forget just how much effort goes into producing it.

Many users also complain about the documentation itself. Often this is because it’s been written by programmers and, as a rule, they really aren’t that great at writing documentation that is particularly human readable.

A day in the life of a MySQL documentation team member

As I mentioned here, I’m a member of the documentation team at MySQL, a job I started back in April. I’ve just completed a major tranche of documentation, and thought it would be interesting to let you guys know exactly what happens in a typical day for a member of the documentation team.

Subscribe to RSS - documentation