Month: October 2007

bookmark_borderJack of all trades Pt. 1

Posted on

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

Working in the software industry, and particularly for a company that has embraced the XP development methodology, I have exposure to, and contact with, most of the other roles in the company. I talk to Marketing to understand to who, and where, we sell our software. I talk to Deployment to understand the real issues they experience when using our software (they are our customers). I talk to Training to make sure we are promoting the same message. I talk to Testing to make sure the bug that I have found IS a bug and should be logged. I talk to the New Feature development teams to understand what they are working on. I talk to the Core team to make sure I’m aware of the myriad of feature requests and bugs that they are fixing, and whether they impact the documentation. I talk to our Support team to understand the common issues being found. I talk to the Architects and product managers to make sure what we are doing fits with the strategy.

Throughout all of this I must have an understanding of both who I am talking to, and what concerns them on a daily basis. I need to know enough about how Marketing and Sales work, what languages the Development team use, and know the business reasons behind why a particular piece of functionality is being implemented, and throughout all of those discussions I have to remember my role, and consider how the information I’m receiving in the discussion may impact the user and, therefore, the documentation.

Frequently I find myself to be the cog that transfers a snippet of information from one area to another. A minor bug fix that relates directly to a new feature. Most times those links are known, but on occasion they are only discovered when one of my team has started to consider the documentation requirements in that area.

Talking to all of those people, these different professions has helped me understand my role, and re-enforced my belief that, whilst writing documentation remains the core part of my job, a large chunk of our value comes from making, and maintaining, those connections.

Perhaps Technical Communicators are the social web of the workplace?

—

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_borderPlanning ahead

Posted on

In my hangover fug I’ve been thinking about stuff wot needs to get done.

One of those things is to sort out my WordPress install as the recent upgrade has left it littered with errors. It seems to be working OK but… well.. it’s annoying.

Other than that, with the bulk of last week concentrated on Louise and her new job, there’s loads to do in the house. Nothing major, but a small pile of “stuff” has slowly grown and needs dealt with.

I’ve also got my presentation for the TICAD conference to hand in this week.

So, I’m going to dial back on my ‘online’ activities this week. Not disappearing but less conspicuous. Maybe. You know how it is…

bookmark_borderThe Architects of Information

Posted on

I’m a member of the Information Architecture Institute (IAI) but I’m still not really sure why.

I joined about a year ago, although I’d been following the website and reading articles in this area for some time before that. During that time I developed a sense that, at a fundamental level, there is a lot of crossover of knowledge and approach between practitioners of Information Architecture and those of us in the land of technical communications.

The IAI website states that:

As the information age rolls forward, our businesses, markets and societies are being transformed into adaptive, connected networks. The Internet of today only hints at the ubiquitous communication infrastructure of tomorrow. The construction of this brave new world requires a new kind of architecture, focused on digital structures of information and software rather than physical structures of bricks and mortar. As we spend more time working and playing in these shared information spaces, people will need and demand better search, navigation and collaboration systems.

Whilst a lot of the work of an IA is focussed on the web, the basic principles of good design hold true regardless of the medium. Given that many technical communicators provide online help which may, or may not, be delivered in a web format or via the web itself (as opposed to viewed locally in a web browser) those same principles can be used here. Even if we consider the production of information for print, the same considerations of information access and structure, personas and task analysis, require a level of understanding and design in which both IAs and Tech Writers specialise.

As an aside, this type of thing is one reason why you should hire a professional Technical Writer and not rely on other people in your organisation “filling the gap”. They may be able to write acceptable english, but information is next to useless if badly structured.

Looking further into the lair of an IA, we find many are now involved in what is commonly known as the “social web” (aka Web 2.0). With information being shared and promoted across many different areas, both geographical and social, the structure and usage of that information needs to be careful considered, and with more and more information sources moving from traditional outputs (print) to modern outputs (web), then the modern day technical communicator has, essentially, become what is now known as an Information Architect.

Strictly speaking it’s more another ‘hat’ for a Technical Communicator to wear but the idea is the same. As well as writing, design, illustrating, and doing everything else that is involved with creating technical documentation, now may need to consider an additional mode of usage, one which has grown rapidly in the past couple of years.

The more I learn about Information Architecture, the more parallels I find. Designing information structures, leveraging an ever increasing set of tools, is fast becoming part and parcel of our jobs (well, ok, MY job at least). Add in the fact that we are, frequently, the people populating those structures then it’s easy to see that there are many lessons we can learn from those in IA.

Related Information:

bookmark_borderDreaming of dreams

Posted on

I had a lucid dream the other morning. Louise had gotten up early and I dozed off again to grab a final 15 mins in bed. When I say dozed off, I really mean that I was vaguely aware of her alarm going off before nodding back off some seconds later. Nanoseconds that is…

When I woke I was aware that I’d just had a very lucid dream. I can remember thinking, whilst dreaming, that the dream I was having was a familiar one and that it would an excellent source for a story.

Let me backtrack a little here.

Some of you may have noted the occasional comment from my Mum, asking me when I was going to start writing a book. I’ll happily admit that the idea intrigues me but, honestly, it’s one thing writing an eloquent blog post, quite another to write a book. Those things have plots, character development, and all sorts going on.

So there I was, just awake and no more, realising that I’d just been dreaming about my realisation that one of my frequent dreams would be ideal fodder for my masterpiece.

I just wish I could also have remember what THAT dream was about… I’ve tried but can’t get any idea of what it involves yet I know I’ve had that dream before, and I know that I realised, WHILST DREAMING IT, that I should use it as the basis for a novel …. honestly, it’s a wonder I managed to get out of bed at all.

bookmark_borderLife with the Cocoon

Posted on

DISCLAIMER: I was given an O2 Cocoon by a PR firm. I am under no obligation to blog about it at all, nor was I to only mention it if the ‘review’ was favourable. If this post offends you, then feel free to leave. But if you were thinking of buying one… read on.

As I mentioned a couple of weeks ago, I’ve been playing with the new O2 Cocoon. I’ve been using it as often as I can and ‘living’ with it since then, bar a week away in Spain, and overall I’m reasonably impressed. What a wonderful word “reasonably” is…

It’s not a stunning ‘must have’ gadget, but it does have some nice touches, alongside a few annoying quirks.

The OLED embedded on the ‘outside’ of the phone is a nice idea. Subtle and effective and probably my favourite feature. However it suffers through implementation. There are two possible scenarios, both centred around the use of the display when receiving text messages. One is when an unprompted text message is received, the display lights up and scrolls the name or number, and then the message itself, across the outside of the screen.

Now if I have it in my pocket this is kinda useless. If it is on my desk it is in full view of anyone who looks, again not so good.

However if I’m in ‘text conversation’ mode, sending messages back and forth, then the scrolling is too slow to be useful, and I don’t need the name/number anyway. So, a smart idea that just feels a little like ‘an idea for ideas sake’. But that’s only on the text message front. The other uses – time, alarm, MP3 track details – make more sense.

Hardware-wise it feels nice in your hand, until you open it and answer a call. I’m happy to concede that it might just be that I’ve got a funny shaped face but the phone never felt comfortable when I was on a call. However the call quality was good and clear, as was the signal strength, of course it may just be that I was in particularly good coverage zones for the O2 signal.

As a It has most of the usual features of a mobile phone and, by and large, the software and features are nothing out of the ordinary but, as it’s being sold as a music player/phone/lifestyle gadget I’ve spent more time trying to use it with that in mind and, on that count it’s not too bad.

Having loaded up some MP3s I found the music player software is a little quirky to operate but didn’t take me too long to master. The sound quality through the supplied headphones is good and in a nice touch you also get a headphone splitter in the box, allowing two pairs of headphones to be connected to the phone.

Alas the main navigation button/joystick, used to navigate the onscreen menus and options is hugely frustrating and I still can’t decide if it’s over or under sensitive. Sometimes it reacts on the slightest of touches, other times a furious session of bashing is required to make a selection and too often that would result in the WRONG selection and another session of guessing where or how to push, flick or tickle the control.

One of the advertised uses of the phone is to set an alarm, place it on the charging dock, and use it as an alarm clock. With the soft blue hue of the external OLED perfectly suited to this, the idea falls flat on its face because the only accessible buttons are far too small to find easily in a state of Again, close but no cigar. It is a neat idea though, with a lot of people using their mobile phones as their alarm clocks anyway. The MP3 of your choice is usually a better choice than whatever dross the radio is spewing out of a morning.
little
I didn’t use the camera much and, in the current climate of 5 and 7 MB models it doesn’t seem a little stingy to only offer 2MB. But for quick snaps and silly video clips it’s fine if not earth shattering.

Overall I whilst there are some faults but then every phone has those and some of the quirks I found won’t affect everyone. In particular the joystick may be fine for others, it is probably just me. However there isn’t that much that stands out other than the OLED display and the provided dock. For me, those don’t make the phone a must-have gadget but if you are in the market for a phone/music player then it’s worth a look. The big question is whether the OLED display and the dock are enough to give it a competitive announcement.

I must admit that initial impressions were good when I got this phone, but over the course of a couple of weeks it fast become just another mobile phone. Given that O2 are the UK network for the Apple iPhone, something that DOES have the ‘wow’ factor that the Cocoon aims for, I think it will take some clever selling strategies to shift many units of this handset.

Finally a word on O2, excellent coverage, and their customer support handled my one and only query efficiently and friendly and it’s more than likely that I’ll switch my main phone contract to them as soon as I can. Orange should take a leaf from their book if you ask me.

bookmark_borderRecently Read

Posted on

Another week, another quick set of links. I really should start using one of these new fangled “social bookmarking” sites for this, shouldn’t I. Problem is I already have a del.icio.us account for personal use, and I like being able to add some thoughts about the links but it limits that slightly.

In saying that, it does mean I give each link proper consideration, rather than just bookmarking them in passing. With that in mind, I thought I’d change the format of this post a little and offer a little more thought on each. Hopefully the links remain interesting and useful to others.

In a (short) post entitled Identical vs derivative reuse Ann Rockley suggests that

“one thing is certain, that companies can reuse more content then they think”

If you are currently investigating reuse opportunities within your company then you should find this interesting. Understanding the potential is a key part to forming your single sourcing business case, and if nothing else it offers some handy reminders of places to look.

Anne Zelenka wonders why companies are moving away from cubicles to open plan spaces to aid communication, and proffers some suggestions in her post titled Mold the virtual space, not the office space

“Lots of web workers are traditional employees and go to an office every day. But they can still take advantage of the web to reach out inside and outside their company.”

In my personal experience, open plan offices are a boon to the technical author in many ways. Physically locating a technical author with the development team that they are working with ensures that they catch all those snippets of information that typically disappear into the ether.

However, the downside is the constant distractions and background noise. As such I tend to spend a few days a month working at home, setting work aside for those days as I know I can tackle larger chunks of work with little to no distraction or interruption.

The first of two links to the ever thought provoking Ann Gentle. Her article The “Quick Web” for Technical Documentation, which discusses using wikis for technical documentation. is available as a downloadable PDF. The article was recently published in the STC magazine Intercom and others sage advice (as ever).

Keeping on the wiki theme, I came across a summary report from an MBA student that covers Managing Wikis in Business:

“indicates that wikis have provided platforms for collaborative and emergent behaviour, enabling people to work/communicate more efficiently and effectively, learn from past experience and share knowledge/ideas in organisational contexts that are not averse to collaboration”

I’ve not read the full report yet, but looks very interesting.

Are you involved with the UI design of your application? Joshua Porter makes the case that you should be as interfaces need editors:

Editing is mostly about clarity and making the interface concise. It’s a lot of copy-writing, and only a little rounding corners.

With a task view of how an application is used, there is an easy ‘in’ to this area for most technical writers.

Sticking with UI design, if you are interested in this area have a look at these articles from Apple Insider. Whilst they are focussed on new elements of the “soon to be released” Apple OS, they start back in the days of early GUI. Fascinating stuff, or maybe just a nice bit of nostalgia. The articles cover the new Dock, Spaces, and Finder.

Finally a doozy of a post from Ann Gentle. It’s the type of thing that makes my head spin and sort of, maybe, ties in with my own thoughts on structured authoring within an Agile development environment. Single sourcing documentation, following a structure such as DITA, matches the fast pace of Agile development, to improve collaboration and make the sharing of discrete chunks of information more open a Wiki makes sense. So, in my mind there is a match, or at the very least a correlation between structured authoring (DITA) and Wikis. However Ann, in discussion with Chris Almond and Don Day, comes to get:

“a sense that there are two camps in technical documentation. There’s the “quick web” folks who connect easily and author easily, and then there’s the “structured quality” camp that requires more thoughtful testing and time spent on task analysis and information architecture. Also, the types of information that these authors are trying to capture are opposed in some senses.”

It’s a fascinating post and has certainly got “ideas popping and synapses firing” in my brain. Are structured authoring and wiki opposing forces? is a question which is going to keep me occupied for a while.

That’s all for now. Next week I’m going to try and NOT feature a post (or two) from Ann Gentle but we do seem to share a lot of similar ideas. Don’t worry, I’ll “spread the love” as they say.

Right I’ve got a presentation on Using Wikis for Collaboration to finish. Pass the caffeine please.