I’ve spent the last couple of days writing an article for an industry magazine. It’s not something I’ve done before and I thoroughly enjoyed the challenge. It was aimed at CEO/CFO level, so was heavy on business aspects and lingo, not something I’m comfortable writing to be honest, I prefer plain english.

However, what really surprised me was how quickly I got into the mindset and soon I was “dynamically leveraging” and “interactively promoting” all sorts of things. Now I need shake myself to make sure it doesn’t creep into my normal technical writing.

Still, it was an interesting exercise and the skillset is the same, it’s only the language that differs. I still needed to write with the correct user in mind, needed to phrase and structure the information in a way that makes sense to them, and I needed to pitch the technical level of the article correctly.

Of course, as the article is for a magazine, the tone could be a little lighter and it was fun to experiment with this. For example, I opened the article with a first-person scenario which although I’ve been writing a blog for a few years now was still a challenge, for this humble technical writer!

I’m waiting on feedback from the PR company, but hopefully it’ll get published. Fingers crossed.

In the coming month I’ll be migrating some content from FrameMaker to AuthorIT and, whilst doing so, I’ll be taking a little extra time to re-write the content to be as re-usable friendly as possible, mainly because it’s likely we’ll be starting to localise our product at some point this year.

I’ve a good idea of what is required when it comes to engaging a translation agency, I was involved a little in this area at a previous company, but have to admit that I’ve not really given the writing style required as much thought as I should’ve.

Still, hindsight is 20/20.

A phrase which, of course, would be hard to localise… ironic.

So I’m doing a little research but thought I’d ask here to see if anyone has any pointers (I’m going to be asking more questions here than I have previously, and I’m also going to steer clear of mailing lists a little, too much noise these days).

Writing for translation then, any top tips? Suggestions or advice?

Danah Boyd has been reflecting on her long lost handwriting skills.

“My ability to communicate without editing has decayed. My patience for creating text at a rate slower than I think has decayed.”

Are we getting lazy? Are we too reliant on technology or are we simply adapting how we work and think to match the new capabilities we have at our disposal.

Personal computers have been around for long enough now that they are a standard, obvious, piece of kit for a technical communicator. I’m 34, and those of you from my era probably won’t EVER have asked whether a PC is part of the provided tools or not, it’s just something that is presumed (asking for a particular spec is different).

So, whilst I still use pen and paper to jot down notes, I don’t ever write anything of any length that way. Contrast that with some letters I stumbled upon the other day, written to my Gran when we had moved to the South of England (there are few in number but her replies are treasured). Written in one go, by hand, I was obviously still capable of editing my thoughts before committing them to ink. These days my tendency is to write first, edit later, publish quickly.

Everything you read here has passed through that (somewhat wonky at times) filter, and it’s a luxury I’ve become so accustomed to that I no longer really consider the process. Editing is such a key part of my written communication, regardless of where it is manifest, that it is now just something I do. It wasn’t always so.

Writing notes at college required on-the-fly information structuring and text editing, due to the simple premise that the less time spent scoring through lines of text the better. I have notes from early training courses which show I still adhere to that principal for at least the first couple of years of being a professional, entire sentences written out by hand with nary a score or embellishment to be found.

Fast forward a few years and my notes quickly descend into random words and scribbled quotes. If I don’t type up my notes the night of a conference, training course or meeting then they take on the cryptographic qualities.

And I guess this is one reason why the prominence of laptops in meetings and at conference venues has slowly risen over the past few years.

The odd thing is that most people acknowledge that note taking works best when pen on paper.

So I’m making a concerted effort to rediscover my inner editor, to take a few extra milliseconds when jotting down notes and thoughts to make sure they mean something. It will take some time but, in the long run, I think it will be worth it.

Technology is wonderful, it has many benefits but sometimes it’s good to step back and rediscover the abilities you used to have.

I started this blog to have a separate place to write about my “professional” thoughts and I guess I thought I could maybe add a little value to the cluttered world of technical communications, or at the very least raise my profile a little. Yes, I have an ego, but it’s kept in check for the most part.

However, like my other blog, the main reason this blog exists is to give me a place that I can consider and process my thoughts. I’ve always found writing things down helped me get a good sense of what they were, even if I didn’t necessarily start with a cohesive picture in mind. Sometimes the simplest issue, one that has eluded me for some time, leaps into focus when I start writing. I’m not sure if it’s always been that way or I’ve now trained myself into such a habit but I’m not complaining, it works for me and I’ll admit that I still get a little buzz when something “clicks”.

If I were in a cartoon a light-bulb would *plink* into existence above my head when that happens. Reality can be such a disappointment.

Today brought a good example of such a moment and rather than deleting my thoughts, I’d thought I’d post them here. Sharing is power after all (badly paraphrasing remains inexcusable).

One continuing theme on most of the mailing lists I follow and in various blog posts across the land, is that of knowing your audience. Knowing why you are writing, and who you are writing for are the fundamental tenets of our profession. They are so fundamental that, if I’m honest, the incessant reminders about them do start to grate somewhat. After all I’m a professional, how many times do I need to be told to consider my audience? How many times do we need to restate something we all know and understand.

I’m happy to admit that some will know more about their audience than others. Some will make do with a rough approximation of what their audience expects, whilst others will interview and analyse their customers and gather requirements and direction directly.

Regardless of your level of commitment to understanding them, anyone who is writing must (surely) consider their audience. Yet, at every turn, the answer to many questions all stem from that presumption, and are presented in simplistic terms. Know your audience they say. OK OK, I get it!

The thing is, after reading such a response for the umpteenth time it suddenly struck me that yes, we do need to be reminded of this basic fact, time and again.

We all have pressures on our work. Whether those pressures come from commitments made to others, from our own professional integrity, or directly from the customer, they all serve to focus us on the end goal and usually to start thinking in terms of quantity. We know we need to document the new interface to the ACME Widget and when pressure is exerted their is a temptation to take shortcuts, and the easiest shortcut is, by and large, to forget the audience.

The cardinal sin allows us to omit information on the presumption that they will “probably know it”, to structure the information according to UI rather than task, and ultimately to regress to a “if you can click it, document it” mentality. That may be a valid mode in certain circumstances but that will depend upon, yeah you guessed it, your audience.

Audience analysis, the use of personas, call it what you will, if you don’t have at least a rough idea of the type of person you are writing for then why bother? You won’t be structing the information correctly, you won’t be pitching the level of information appropriately, and you most certainly won’t be thinking around the various conceptual models your audience are likely to use and understand. The more you know, the better you can focus your documentation, drilling down into the tasks they need to complete and what they need to know before they begin. The better your knowledge of your audience the more likely it is you’ll produce documentation that they can use.

Put it this way, if you aren’t writing for a specific audience, who ARE you writing for?

Ooops.

I’ve gone and done exactly what I said annoyed me, lectured you all on knowing your audience when you already know that you need to know that. You know?

Next time I read yet another “Depends on your audience” response in a mailing list I’m going to try and remember that advice and apply it to my current work.

Addendum: Charles Cooper has been considering the same thing.

Daniel Scocco is wrong. Not completely but fundamentally wrong enough that I need to call him out on his errors.

He points out Six Common Punctuation Errors that Bedevil Bloggers and, whilst all are grammatically correct, I think he is missing a point. Now on a technical level, as someone who writes for a living I, like most people,agree with him. I’m not posing what I’m about to say as an excuse not to write properly nor as any reason to ignore some basic rules of grammar but there is part of me that doesn’t think that the casual writier need to be as concerned with the laws of writing as a professional writer.

In other words, I know the law but I am not a policeman.

So let’s look at the six suggested rules:

1. Apostrophe for Plurals
OK, I can’t argue with this one at all. It is wrong people, stop doing it.

2. The Comma Splice
Whilst grammatically correct, it’s at this point I start to ponder what grammar means in terms of conversational text. A lot of bloggers aren’t trained writers, they have a basic grasp of grammar but little more, and it’s not something that concerns them. They are, typically, telling stories of a personal nature and mostly they adhere to a narrative take on writing.

Essentially they use punctuation to help phrase their sentences and see no reason not to use a comma as a “pause”, nor to use quotation marks for emphasis.

3. Quotation Marks for Emphasis
We’ve all seen the two-fingered air quotes used in film and I’m pretty sure we understand that they aren’t actually quoting anything, merely indicating a level of sarcasm. I will plead guilty to having done this on my personal blog where I tend to write freely.

4. Multiple Punctuation Marks
Technically correct. But there is a part of me that can only just muster enough energy to shrug this off, colour me apathetic. I don’t think either example is less-readable than the other.

5. Punctuation Outside the Quotation Marks
See Point 4. Ohhh and the main thing that annoys me about this kind of thing isn’t the grammatical inaccuracy, but the shapes the punctuation marks form.

6. The Missing Comma After Introductory Elements
I find this one surprising. As I mentioned in Point 2, most bloggers (or at least the ones I read) use a comma as a pause and the example given suggests that they’d use one there anyway.

And anyway, what does “Joe stopped on my house” mean?

I’ve commented on this kind of thing before, whilst I am a writer by trade I do think that, occasionally, we thrust our own perfections on others under the auspices of the common good. Everyone who speaks English should know these rules and adhere to them, we say. I’m sure other professions do the same, the joiner visiting my house will look at some of my attempts at D.I.Y. and shake his head in dismay. The key difference for those of us employed as writers is that our skillset is so widely used that the myriad of different abuses that assault our eyes on a daily basis make it all the harder to stomach.

As others have mentioned, the rules of grammar are interpretative and also depend on both where they were learned, and the location (and knowledge) of your audience. I totally agree with Daniel, if you are serious about your blogging then learning to write well is important. The real key is learning to write as well as your audience expects.

Well, it made me chuckle…

The following is taken from current experience, fitting a Publications team into an agile (XP) development methodology. It’s very much a work in progress…

~

In a more traditional development environment, there is likely to be specifications and design documents on which you can rely. This is not the case in an agile development environment, with requirements focussed around user acceptance, and a heavy reliance on word of mouth (through pair programming) and shared knowledge. It may sound chaotic, it is not. Each piece of functionality is assessed and if there is not a direct requirement for a piece of functionality it doesn’t get done, similarly each piece of functionality is stated as a story, and will have an index card created which can be used to track the story through various stages.

To match the pace of software development, the Publications team needs to adopt a similar approach. Rather than waiting on information to come to us, we need to be involved, engaged and pro-active in learning and understanding what we are documenting, and breaking out of the old authoring model.

Previously large chunks of documentation were written by the same person, often at one sitting. You’d outline a chapter and start bashing in the words, investing a lot of time and effort into your ‘baby’. That concept is no longer applicable.

The trickle method relies on the ability of the technical author to retain a “big picture” view whilst working on multiple chunks of information at any one time. The information will not come in a set order, nor from a definitive source, instead it will trickle in from various parts of the development team, testing, and so on. Your job is to monitor the flows of information, position yourself within a stream (or two) and divert the information you need into the documentation.

As such, the technical authors will be sat within development teams and are expected to attend all designing and planning meetings. Understanding as much of the work as possible, as early as possible, will benefit the documentation, and having a technical author in place at the beginning of the development process will benefit the product. Be the user advocate, keep the tasks they will be performing in mind and strive to contribute as and when you can.

This way of working is different, and does mean you need to adjust your mindset somewhat.

You will not:

• Be able to write entire sections in one go.
• “Own” the document you are working on.
• Always finish what you started (but only if it’s planned that way!!).

Hopefully this new approach will make us much more involved in the day-to-day development of the product, and by bringing additional benefits to the development team, will increase our standing with them.