Tag: RTFM

bookmark_borderWho cares if they read it or not?

Posted on

RTFM

Seriously, do we spend too much time worrying about this? What do we get paid for after all, to write documentation, so that’s what we should concentrate on doing. So what if no-one reads it, as long as I’ve done my job I’ll get paid.

And no, I don’t care if they don’t understand how to use the product properly, if they choose not to read the documentation then there isn’t much more I can do, is there? Yeah, they might get stuck but if I can learn it, so can they. If not then maybe they shouldn’t

Pander, pander, pander. I’m sick of it. The documentation is perfectly good and until people learn to read it then they really should stop complaining. Ohh and if they choose to look on the internet for an answer to their question, good luck! We all know that those bloggering things are a lot of rubbish and no, I don’t use that Twatting thing either, what a waste of time. Don’t even start me on Facebooks.

I’m perfectly busy enough, doing the job I was paid for, so yes, they should RTFM and it’s not my fault if they don’t.

…

Obviously I’m jesting, but this seems to be a bit of a hot topic right now, and rather than rehash what has already been said, I’d highly recommend you spend 10 minutes of your day reading the following:

I guess it’s safe to say there are challenges ahead but hey, it’s a new year, what better time to start tackling them.

bookmark_borderThanks for complaining

Posted on

Ever get the feeling that no-one reads your documentation? It’s a frequent issue amongst Technical Writers and the general stance reflects the approach many take to make sure that, when someone finally picks up the documentation, they can get to the information they need as quickly as possible.

Given that, there is little worse than to have errors reported in your documentation. After all, if they’ve only just started using it to help them solve a problem and one of the first things they spot is an error then it’s understandable that confidence drops and that they are less likely to go to the documentation in the future.

Of course we all do the very best job we can, yet the fact remains that mistakes happen, errors occur. The reason that this tends to be a bigger issue for information is down to how we process the knowledge we have.

Without getting into too much detail, learning is a continuous process and most of that happens when you are doing things, using the tools at your disposal and figuring out how they work and how they help you achieve what you are trying to complete. By the time you decide to check the documentation, you’ve (usually) got a good bank of knowledge already, and it’s building all the time.

So, when the documentation is wrong (regardless of whether the reader spots the mistake immediately or only realises it after trying out the instructions) it seems to be an obvious mistake. After all, if I can figure out how to do X, why is the documentation wrong for Y, it’s just the same process?

Software applications that have minor errors in them are tolerated because they are the tool and sometimes there isn’t an alternative. You learn how to accomodate those errors in the application and work around them. You can’t do that with documentation, it’s either right or wrong (ambiguous documentation is presumed wrong) so confidence in the rest of the information is linked to those initial few instances of usage.

We all have review procedures that should capture errors in the documentation, we do our best to think about how the user will be interacting with the product and base the structure and content of our documentation on that information, and we all receive that email that says “On page XY of the User Guide, it states that…” and our hearts drop a little.

However I think we should embrace those moments, be positive about them! You have a user who cares enough about the documentation to complain and I think it’s worthwhile thanking them for pointing out the error, tell them that it will get fixed, and encourage them to continue to let you know if they spot anything else.

So next time you get one of those emails, or a bug in the documentation is raised, be sure to follow up with the user and thank them. They are proving that people do RTFM.

bookmark_borderHow to make a cup of tea

Posted on

Further to my Too Simple post, and in response to the comment from Annie about the state of software manuals, I thought I’d try and give a bit of insight into the basic workings of my profession. Yes, that’s right I DO have a day job. I am a technical author and I write software documentation (actually I don’t like the “technical author” job title but that’s a different story).

Before I begin I’ll state that I’m not the most experienced technical author (there are people who have been doing this for 40 years), I’ve only ever worked in a software environment, and as in most professions there are a number of different methodologies and working practises which I can choose to follow. OK, caveat finished.

Ohhh and you may be wondering about the title of this post so let’s start there, how DO you make a cup of tea?

It’s a question I’ve used in a writing test (for graduate technical authors or those new to the profession) in the past, and it’s usually fairly effective at giving a rough first impression of how the candidate thinks in relation to product documentation.

Now, I’d warrant that most people reading this have some idea of how to make a cup of tea, but let’s presume that you didn’t, in fact, let’s presume that you haven’t even heard of tea. Starting to get a little tricky, isn’t it.
Continue reading “How to make a cup of tea”

bookmark_borderRTFM

Posted on

I’m published baby, yea!

Finally got around to writing an article for Speakeasy, and whaddya know, that nice bloke Carey published it (and only a couple of grammatical errors to correct too, which were only in there to see if he was paying attention…). Titled “R.T.F.M. – The plight of the Technical Communicator” it is an insider view of my profession, or at least one aspect of it. If you’ve ever used product documentation, it might be of interest.

So what are you waiting for? Go read it now.

bookmark_borderFree Book

Posted on

OK I’ve only skimmed a few pages of this, but it looks good so far.

What is it? “A few months ago a group of writers with Web sites decided to get together and make a book. The idea was for each writer to compose a story on the theme ‘How-to,’ to result in a bound volume titled ‘Manual.'”

So go ahead and Read the Fucking Manual – RTFM indeed.

To comment, or not to comment…
The majority of the sites I visit have a comment facility of some sort, and I’ve been toying with adding one myself for sometime now. The one thing that keeps stopping is maintenance.

Battleground God
Answer 17 questions about your religious beliefs (this is aimed a those of christian denomination): “Our battleground is that of rational consistency.”
Play Battleground God or Check my results.