Month: April 2008

Recently Read

Another week has zoomed past, and I’m only now catching up! I’ve been helping out with our development group retrospectives… but more on that later. For now, here are a few things that caught my eye this past week.

Gatekeeper vs. team member
Whilst not directly talking about technical writing, there are some good points in this post, with several mirrors between some of our [sic] processes and that of the self-publishing author:

…some authors, trusting no one but themselves, will put out what they have to say, untouched by any other person. Sometimes this works. Usually it doesn’t. Others will reject the criticism of experts but accept the flattery of a subsidy publisher. Others will embrace the traditional publishing process and accept the input of those who have more publishing experience than they. Others fall along the full spectrum in between.

Is single source always the best option?
Single source, rightly, gets a lot of press and for a lot of companies would be of benefit. However it can be hard to convince others of those, here’s an example:

I know a single source of content will save me a lot of work. But for other people in the company it won’t. It will mean more work for them, not to mention a very steep learning curve, an investment in software and a strong training committment. It will save me lots of time and effort—in the long run—but it’s going to double the work effort of ten other people. Where is the benefit?

The last business case I pulled together this was the sticking point as well. Understanding the pain points, and how much they cost the company is key and the benefits need to be realised over a longer time period than you’d think.

Are you part of the industry conversation?
Anne Gentle (via Twitter) pointed out that Sun now have a formal blogging policy in place for their employees. It’s a great step and shows that they understand the role that blogging can play:

… By speaking directly to the world, without benefit of management approval, we are accepting higher risks in the interest of higher rewards. … The real goal isn’t to get everyone at Sun blogging, it’s to become part of the industry conversation.

Confluence Wiki adds page ordering
I’ve talked about Wikis before, and largely I think the core value comes through long-scale collaboration and, as such, haven’t really considered moving our documentation set to a wiki. There are very good cases for wiki-fying your documentation set of course, but for me there are one too many limitations. This news from Confluence is starting to change that as summed up by Sarah:

When you’re writing a documentation set, the sequence of the pages and chapters is very meaningful. It’s nice… well, many would argue that it’s essential to be able to define a logical page order rather than being stuck with an alphabetical order. Up to now in Confluence, we’ve worked around the problem by manually adding chapter numbers and page numbers, like “1. Introduction”, “2. Installation Guide”, “2.1 System Requirements”, and so on. Now take a look at point 2 in the Confluence 2.8 Release Notes. We can just drag and drop the pages and chapters where we want them. They stay there 🙂 and the new order is reflected in the PDF outputs and hierarchical page-tree views

Thinking like a user
I spend a fair amount of time reminding developers that they have a different mental model from (some of) our user base and that the design may be improved by taking the point of view of the target user. However I should confess that I fall into the very same trap myself:

the problem with being able to think like a user is that familiarity breeds … well, familiarity .. we’re using (at least I hope we are) the applications that we document daily … building a store of information about the application [and] we can easily lose sight of what the new user, who comes to the application tabula rasa, may experience.

Yup. Guilty!

Word 2003 Tip: Edit in Print Preview mode
I didn’t know this one either. You truly do learn something new everyday.

Are you pondering what I'm pondering?


I’m thinking.

I’m thinking about what to write.

I’m thinking that I’m not sure where the tub of Polyfilla is, I’m hoping it didn’t get thrown out.

I’m thinking that I shouldn’t really be writing this post as my entire week is chock full of meetings and I need to grab every single available moment to ping off some emails and keep up to date with what’s going on outside of the meeting rooms which are currently almost a semi-permanent home.

I’m thinking that finding a better way to do things AFTER you are committed to a particular way of working is a little daft…

I’m thinking that having all 103GB of my music here at work is actually a bad thing as I spend WAY too much time flicking through tracks to find something that suits my mood.

I’m thinking that I really REALLY enjoyed the Pixar book I finished reading yesterday (it was a Christmas present) and that I should post up my thoughts/review but I don’t currently have the time.

I’m thinking that I should stop thinking and get something done!

What are you thinking?

Harissa Paste

Picture the scene, if you will, of a dashing and debonair young man, slim of body with flowing locks of blonde hair framing his sculptured face as he lounges gracefully on a chaise lounge. Soft music plays in the background, whilst the delicate fragrances of dinner waft from the kitchen. A tranquil scene I’m sure you’ll agree.

Now picture the exact opposite, a slovenly baw-faced guy slouching in front of the TV, his belt undone, his thinning hair needing cut, his face unshaven.

That pretty much sums me up at the moment, but then it’s been a busy weekend.

Friday night found me dashing into Glasgow to catch Elbow at the ABC. Doors opened at 6pm the ticket said, something I only realised at 6.04pm when I lifted my ticket to put it in my jacket pocket for later. Of course, having jumped in the car and raced into Glasgow, I arrive at the venue to find a growing queue standing outside and received confirmation from the bouncers on the door that doors didn’t open until 7pm. And yeah, it didn’t matter what my ticket said, alright?!

Minor glitch over, the gig was pretty damn good. I was largely going on the strength of their last album, having not had much chance to hear their new one, nor having spent much time listening to any of the others. It didn’t matter though, as the band were pretty slick, and BOY can that man sing, what a voice (although I should mention the quality of the sound, it was spot on, you could pick out every instrument and voice). Top gig, and I got to meet Paul as well, bonus!

Saturday and we were up early, with the car filled with a variety of rubbish to be taken to the dump, then a quick bit of shopping and a few other chores before heading back home. Then, alas, it was off to work for a few hours before hooking up with my parents for dinner.

And today saw some DIY, the fitting of a new light in the kitchen and a few other tidy up tasks as we continue to return our house to some sort of order.

Ohh yes, the kitchen… it’s lovely, thanks (see for yourself)

Anyway, harissa chicken is cooking on the oven, some roast vegetables will be going on soon so I’d better get the table set and open a bottle of wine. Hope your weekend is ending as well as ours.

Recently Read

Ahhh, the end of another week (well it will be in a few hours, just a few last diagrams to be rebranded…), which means it’s time for a quick roundup.

Pilcrow & Capitulum
A nice little post for the font freaks (guilty!) discussing the evolution of the that little symbol that is often used to mark the end of a paragraph.

It’s tempting to recognize the symbol as a “P for paragraph,” though the resemblance is incidental: in its original form, the mark was an open C crossed by a vertical line or two, a scribal abbreviation for capitulum, the Latin word for “chapter.”

Open Applications – A Model for Technical Documentation?
Ferdinand Soethe takes a look at the Open Source movement and finds several parallels and arguments for basing a technical documentation effort on the same principles. It’s not all a perfect match but this confirms some of my own suspicions.

Talking with Technical Editors on the topic of Single Source Publishing (SSP), one sometimes gets the impression of talking about Utopia. (Nearly) everyone knows it, nearly everyone could well use it in their work, but hardly anyone actually uses it.

The necessity to prepare contents for different target media can neither be really met with classic text processing or DTP systems nor with Web design tools. This was why the XML language family born in the 90’s found huge acceptance in the area of Technical Documentation.

Rethinking Community Documentation
An old but still valid and fascinating article exploring the changing landscape of technical information:

The way we educate ourselves to use and program computers is shifting along many of the same historic lines as journalism, scientific publication, and other information-rich fields.

As an industry much has changed in the two years since Andy wrote this article but it’s still worth a read, particularly if you are looking at launching your own technical community initiative.

Three Ways to Get Developers to Keep You up to Speed

A simple reminder of how to get things done, the kind of advice that sometimes seems very obvious until you read it and realise you aren’t doing it! I’m tempted to print out the three “rules” and pin them to the wall.

Get support from those whose voices everyone takes seriously. Chances are, you were hired because someone thought documentation is important. You may find yourself in an environment where you have to prove your importance, and many times that is a battle fought for a matter of inches rather than miles.

As ever, I’m keen to hear about any other technical writing/communications focussed blogs, in any area. If you write about your job, regardless of your industry, do let me know.

Usability sucks

I’m getting royally fedup with a lot of what I read that is written in the name of usability. Maybe it’s just a personal loathing of the overly academic, or perhaps I lean towards simplicity a little too heavily but SHEESH, some of the better known experts can’t half prattle on…

I’m a member of the usability team at work, largely because I made a lot of noise about it when I joined the company, but also because as a technical communicator who is passionate about the entire experience of using a product, I realise that the interface is THE most important part of communication between user and product.

I’ll let that one sink in, shall I?

Despite our own protestations, we all know that while good documentation is crucial to a product, it’s the user interface that carries the bulk of the load of communicating the capabilities of the application. With that in mind it makes sense to be as involved as possible with the design of the interface for, as I read somewhere many moons ago, we [technical communicators] are “the interface to the interface”. So, if nothing else, getting involved in usability and screen (UI) design for your application should make the job of documenting the software a lot easier.

Now, I’ll happily admit I’m still very much a novice in this area, but I’ve picked up enough knowledge over the years to be dangerous. I’m very aware that my advice tends towards what I would consider common sense, but generally speaking I base my UI design comments, and generally usability thoughts, on the following processes:

  • Simple task analysis – picking out the main usage of the application should be pretty straightforward, but sometimes narrowing that down into distinct tasks can be trickier, so I tend to mentally “step back” everytime I approach a new screen and ask myself what it is I would WANT to be able to achieve given where I am in the application. Often you will find that the flow of the UI isn’t quite right.
  • Narrow your view – the next step is to pick out each control to make sure the label, text or icon make sense. It’s very easy to get caught up in the overall task and presume too much.
  • Quick, write something! – this step can be done mentally, with pen and paper, or just start typing. I often find that it’s only when trying to “tell the story” of how to use an application that all the pieces finally fall into place… and then you realise that one is missing.

As I said, I’m no expert but my approach seems to give reasonable results. Yes with formal analysis, metrics and so on, you can always improve things but sometimes perhaps good enough is good enough?

I sometimes wonder if I’m actually doing more damage than good so I’m quite careful that my opinion isn’t the only one (ok ok, isn’t the LOUDEST one), and I try and keep up with things – Boxes and Arrows & Jakob Neilsen for example – and I’m convinced that there is a big enough overlap between the two professions that one day I’ll be hiring a “usability writer”. No… a “technical usabilitist”…

Real life will resume shortly

Before I say anything else, a quick but very heartfelt thank you to everyone who has offered advice, support and general nice thoughtyness (either in comments or via email or Twitter) concerning my recent health news. I’m not going to go on about it, but thank you.

Elsewhere in my life, the kitchen has been fitted! The tiler arrives today (phoned last night to see if he could come early) which means I’ll be free to do the flooring at the weekend. After that, a little bit of wallpapering (I’m sub-contracting my parents for that bit, they are pretty cheap but I have to do all the high bits…), a new light, new blinds and I THINK we are done.

Just the rest of the house to return to order and to await the delivery and fitting of three replacements doors as two were slightly damaged, one was completely the wrong colour. The kitchen fitter mentioned the damaged doors to me over the phone, but as they were gone by the time we returned home I have to admit that we can’t see even a tiny scratch. Oh well.

The past day or two have been a funny mixture. Looking back it seems like I’ve dazed and floated my way through them, but with specific instances of chaos peppering my (rose-tinted) view. Between the kitchen, the doctor, “release week” at work, and the usual demands of modern society (bills and whatnot.. meh), my mind has been shotgunning all over the place. It’ll be nice to find a few quite hours on Saturday night to sit still and zone out.

In saying all that, I’ve still to draft the letter of complaint concerning the bodged survey (which lead to 4 and a bit weeks without a kitchen!) so I’m still not entirely sure how much the kitchen will cost us. I’ve been trying to calculate, in monetary terms, how much to demand they lop off the bill and whilst it’s easy for things like laundry costs, days holiday taken without need, and so on… how do you put a price on “stress” or however it’s classed (hmmm, perhaps mention of my high blood pressure too…).

If we round down to the nearest thousand, we’d be demanding a reduction of around 4.6%. We’ll see, I’d rather have a few hundred quid in my pocket than theirs!

Speaking of money I really must order some Forints…

A kick up the arse

So I’m now on pills for my blood pressure and next Tuesday they take blood to check my liver and kidneys are functioning correctly, and to see what my cholesterol level is at the moment.

Then, later that day, I get an ECG.

It’s all a bit… much really. As I feel fine but the numbers don’t lie.

The disappointing thing, the thing that really fucks me off, is that for the past two weeks I’d been careful with my diet, cut out as much salt as I could, and managed a few short walks (still not enough I know but my knee still isn’t 100%), yet my blood pressure went up!

Edit: Read on at your peril, it’s a bit maudlin and ranty and ‘teenage angsty’. Don’t say you weren’t warned. The short version is, “I’m fine, I’ll be fine, I just need a moan”.
Read More