Let's face it: GNU/Linux software is not always easy to use. Especially command line software (at least the GUI programs have buttons and tooltips). Sometimes, the program will have a manual or some documentation at its homepage, but that is not always the case. The solution? The magical man.
You know what I'd like to see? I'd like the various Free software groups (whether they use "open source" or "free software" doesn't matter) get together to produce the greatest educational tool the world has ever seen:
A website dedicated to Free / Open Source code. Not programs. Code.
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.
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.
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.
Well, it's been completed a few weeks now, but I've finally reworked the Connector/MXJ and Connector/J sections of the MySQL Reference Manual, which in turn means the Connectors chapter has been completed.
One of the ongoing problems with documentation at MySQL is that it is getting ever larger.
Not only is the size of the docs increasing, but the formats and languages that we support is increasing too, and that is making it more and more difficult to effectively list them and make sure they are available.
Earlier this week I released the revamped Connector/NET documentation. This is part of the wider Connectors chapter rework, which I'm currently finishing by doing the Connector/J and Connector/MXJ documentation.
Connector/NET provides a full ADO.NET compatible interface to MySQL and is compatible both the Windows .NET and Mono installations.
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?
Probably the most frequently asked question to the docs team at MySQL from the public is “I want to translate the manual into [insert language]”. That language can be anything from one we already have, through to some comparatively obscure suggestions.
I noticed this piece from Johan Andersson on Writing NDBAPI programs—connecting to MySQL Cluster last week, which shows you how to use the NDBAPI—the programming interface to the MySQL Cluster system. By coincidence, we enabled the NDBAPI documentation today. It consists of two elements:
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.
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:
At the developers conference this year, held in Sorrento, Italy, I was fortunate enough to meet and have dinner with some Italian MySQL users—some of whom had travelled from Rome to be with us that evening at a lovely traditional Italian restaurant just off one of the main squares.
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.
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.
Dave Mohyla is the president and founder of dtidata.com, a hard drive recovery facility based in Tampa, Florida.
TM: Where are you based? What does your company do?
DTI Data recovery is based in South Pasadena, Florida which is a suburb of Tampa. We have been here for over 10 years. We operate a bio-metrically secured class 100 clean room where we perform hard drive recovery on all types of hard disks, from laptop hard drives to multi drive RAID systems.
Since the very beginning, directories (of any kind) have had a very central role in the internet. (I have recently grown fond of Free Web Directory. Even Slashdot can be considered a directory: a collection of great news and invaluable user-generated comments. As far as software is concerned, doing a quick search on Google about software directories will return the free (as in freedom) software directories like Savannah, SourceForge, Freshmeat and so on, followed by shareware and freeware sites such as FileBuzz, PCWin Download Center and All Freeware (great if you're looking for shareware and freeware, but definitely less comprehensive than their free-as-in-freedom counterparts).
Mark Shuttleworth is the founder of Thawte, the first Certification Authority to sell public SSL certificates. After selling Thawte to Verisign, Mark moved on to training as an astronaut in Russia and visiting space. Once he got back he founded Ubuntu, the leading GNU/Linux distribution. He agreed on releasing a quick interview to Free Software Magazine.
I read David Jonathon's article Anybody Up To Writing Good Directory Software? the other day, which got me thinking about software directories in general. As David mentioned, many of the software directories one finds when doing a quick google search are free as in beer, not as in freedom. But what interests me is the software directories that already exist, providing a combination of both free as in beer software, and open source software. Sites such as Freeware Downloads and Shareware Download don't advertise themselves as providing free as in liberty software, but each of them have a good selection of open source software available... if you know where to look.
If you’ve ever spent hours at work doing mailings, cursed your printer for printing outside the lines on your labels, or moaned “There has got to be a better way to do this,” here’s the solution you’ve been looking for. Working smarter, not harder! Worldlabel.com, a manufacture of labels offers Open Office / Libre Office labels templates for downloading in ODF format which will save you time, effort, and (if you want) make really cool-looking labels
A little while ago, while talking in the #drupal mailing list, I showed my latest creation to one of the core developers there. His reaction was "Wow, I am always surprised what people use Drupal for". His surprise is somehow justified: I did create a site for a bunch of entertainers in Perth, a company set to use Drupal to take over the world with Entertainers.Biz.
Update: since writing this article, I have updated the system so that the whole booking process happens online. I will update the article accordingly!
More and more people are discovering free software. Many people only do so after weeks, or even months, of using it. I wonder, for example, how many Firefox users actually know how free Firefox really is—many of them realise that you can get it for free, but find it hard to believe that anybody can modify it and even redistribute it legally.
When the discovery is made, the first instinct is to ask: why do they do it? Programming is hard work. Even though most (if not all) programmers are driven by their higher-than-normal IQs and their amazing passion for solving problems, it’s still hard to understand why so many of them would donate so much of their time to creating something that they can’t really show off to anybody but their colleagues or geek friends.
Sure, anybody can buy laptops, and just program. No need to get a full-on lab or spend thousands of dollars in equipment. But... is that the full story?
