bookmark_borderCalling All Scottish Technical Writers

(OK, mainly aiming at West of Scotland)

Following a recent discussion about ISTC local area groups, a few of us based in the West of Scotland have decided to try to set up a local group.

Our first meeting will be on Thursday 15th January 2009. If you work in the area (or further away), please come along to meet other writers and talk about technical writing.

We’ll meet at 7 p.m. in the offices of Sumerian in Glasgow city centre, at 19 Blythswood Square, Glasgow G2 4BG. Tea & coffee provided.

If you plan to come along, please email me so we can get a rough idea of how many writers might be attending:

gordon [DOT] mclean AT gmail [DOT ] com

(if you can figure out the email address you are allowed to attend 😉 )

Now, what on earth will we talk about??

bookmark_borderThanks for complaining

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_borderJack of all trades Pt. 2

My name is Gordon McLean, I am a Technical Communicator* and I am proud to be a jack of all trades.

I recall once being asked to breakdown all the skills required to be a Technical Writer, and then to provide a list of daily work tasks. The list of skills was to be used as part of a skills/training matrix, and the work tasks were to be mapped to a timesheet system.

At first I concentrated solely on the Technical Writers role, but even then you need to wear a number of hats; researcher, analyst, information architect, publisher, indexer, illustrator, proof-reader, editor… ohh and writer. All of those are unique job roles in some places yet, as a Technical Writer, you need to be able to successfully take on those roles to some degree. In most software companies a large part of the job is learning the new features, and as you have access to early builds, you are frequently also playing the part of ad-hoc tester. Admittedly you are usually only testing one scenario, and that scenario is the happy path that will be documented, but a bug is a bug and that means being able to identify one, discuss it with a tester or developer, or both, and why not log it as well?

If you are documenting an API or developer toolkit then, in those instances, you frequently don the cap of novice developer, asking the questions you expect them to ask, before switching caps to presume the role of an experienced developer and wondering if the information you are providing is too simple for them to use or if, perhaps, the structure of the information needs altered.

You need to be able to talk to developers and so you need to know a little about whichever code language they are working with, that way when they mention methods, you can ask whether they mean static or instance.

None of these skills/roles are the core part of a Technical Writers job, but simply additional strings to your bow. The more you know about everything, the more value you can add, so long as you don’t let that detract from your core responsibility, to provide documentation. However, the more you know about everything, the better that documentation will be and the higher your value will soar.

Prompted by The Top 5 Reasons to be a Jack of all Trades

* Communicator/Writer/Author, pick one. I favour ‘communicator’ because I don’t always communicate through writing, sometimes through UI design, sometimes through infographics and diagrams. You get the picture (pun intended!).

bookmark_borderDo you RSS?

Over the past year or so, as I’ve started to struggle to keep up-to-date with the multitude of websites that interest me, I’ve increasingly turned to RSS feeds to help me manage the load.

With that in mind, I’ve been compiling a list of Technical Communications feeds that I find interesting. Some are by Technical Writers, some are not, but I generally skim through the new items daily and I’ve yet to have a day when I didn’t read or find something interesting and useful.

If you have an RSS newsreader, then feel free to grab a copy of my subscriptions. If you right-click that link you should be able to download the file, and then just import it into your newsreader of choice (I prefer Google Reader).

And, of course, I’d love to know if I’m missing any. Hope you find this useful.

bookmark_borderEvolution of language

I’m a writer by trade (technical writer/author/communicator) and have spent long meetings discussing various style issues, how to handle bulleted lists (capitalise the first word of each bullet? end each bullet point with a comma, preface the list with a colon), the finer points of US versus UK spelling and grammar. Frequently I’d get frustrated, mainly because a lot of my co-workers (especially one at Dr.Solomons) were… well let’s just say a little anal, about the whole thing.

So this article, by Jean Weber, Escape From the Grammar Trap was very refreshing, and it’s not just for Technical Writers, we can all benefit from this kind of general advice.

(And yes I’ve calmed down a bit now)