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.