Dear writers of technical documentation,

Today I’m writing this open blog post (unlike those closed, diary blog posts where I complain that life isn’t fair and then lock away?) to make a small request.

When you’re writing documentation (which is awesome) it’s great when you provide sample commands. It really makes it understandable what I need to do to perform that bit of dark Linux wizardry. A sample command alongside with the command itself is basically perfect, since it explains me what to do, and then gives me a real life application.

Some of you, however, and I’m looking in the direction of a lot of MySQL documentation pages, seem to think that it’s a good idea to only use the sample command when explaining something. And that’s bad. Why? Because if I landed upon your page, looking for a magic spell to make my server do my bidding, and you are using a sample command without context…

I have no idea what is going on, or what goes where.

The example in question is a bit of MySQL wisdom that is found on this page. Being the eager beaver I am, trying to clone that gigantic database, I ran into authentication problems. Because I wrongfully assumed that the command was to be taken literal. Only on a second pass and doing some more Googling did I realize that instead of root:root I had to provide the actual username and password. I’ll admit that I didn’t pick up on this “hint” because I never used the password “root”. I’m told it’s a capital sin, the sins of all sins, so to see it in documentation surprises me a bit.

Now, I understand that writing things like I did in my notes can be a shore. For reference, I translated it into this:

mysqldbcopy –source=(user):(password)@(server) –destination=(user):(password)@(server) (database):(databasecopy)

The funny thing is that, when you click the reference to the mysqldbcopy page, they’re using an example that’s a bit post clear, by using –source=root:pass@localhost instead.

Maybe I’m just nitpicking or trying to shift the blame, but some context of sample commands are nice, especially if you dive head-first in using example settings.

About twelve months or so ago, I got really into photography. As is the case with many people infatuated by their hobbies, I thought I needed the latest and greatest equipment. Knowing myself and my impulsive behavior, I managed to keep costs low by not spending money on fancy equipment I’d never use.

I do, however, have the feeling that I wasted a lot of money on my NAS.

We all know  it’s important to have back-ups of important files. And sometimes, back-ups of those backups. That’s why I figured that investing in a NAS was a good idea. I could use it to keep all my photos. It’s a NAS! What can go wrong!

Well, for once I’m fortunate in being impatient, because I always stored my pictures to my computer first, then made a back-up to my NAS if I felt like it.

That might sound like a bad idea, but since buying it my NAS practically “died” on three separate occasions. Each time, the useless black brick that was supposed to keep my pictures safe said “You know what? I can’t read those hard drives anymore. I’m just going to ask you to wipe them.”

This happened for the third time this weekend, after I got back from France. Disk 1 and Disk 2 no longer exist. Want to format disk 3 and disk 4 and start over?

A back-up of the back-up

Fortunately, I’ve got a back-up of my back-up. I bought a €99 external HDD after I got tired of the shenanigans. I’m considering buying a second HDD, because compared to the plastic brick sitting in my “nerd corner”, it’s got the following advantages:

  1. It costs a fifth of a new NAS.
  2. It doesn’t take forever to boot, despite being as empty as the Sahara desert.
  3. It doesn’t MAKE AN AWFUL LOUD NOISE when it’s sitting there, doing nothing.

Fingers crossed that I can still get my money back.