Tag: UI

Jack of all trades Pt. 1

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!).

Recently Read

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.

Technical Writing Evolved

The following is largely focussed on the software industry as that is where my experience lies.

I’ve been an on/off member of the TechWR mailing list for many years now. I dip in and out of threads depending on my current work and knowledge levels. The membership of the list is fairly wide-ranging, with people involved in all sorts of technical communication activites across many different industries. This gives any discussions around our profession and interesting slant as, by and large, the constituent parts of what it means to be a technical writer, and the daily activities involved, are somewhat tied to the industry in which they work. My experience is largely in the software world, but many of the other list members have wholly hardware-based experience, yet others work in highly regulated environments, and some flit from contract to contract, job to job.

A while ago a discussion about how our profession was changing kicked off and the range of responses was fascinating. This wasn’t a surprise of course, the list is full of passionate and intelligent people, but did have the effect of causing me to sit back and reflect a little more on what I do for a living and how, ultimately, it’s a fairly unique profession.

The discussion centred, mainly, around how the emphasis for a lot of technical writing jobs is swaying more and more towards a more integrated approach to the role and how it fits within a team than the historical basis of being heavily centred on writing. The presumption (largely being pushed by those of us in the software environments) is that the skillset a Technical Writer brings to a team extends beyond “just writing the docs”. As a customer advocate, we can (and should) influence UI design and the functionality of the product, and increasingly we are involved in the early design discussions, get hold of early builds and so on. To a small degree, today’s Technical Writer whilst retaining the core function of writing documentation, also dabbles in UI design, functional analysis, sanity testing software (note: this is not QA by any means!) and may even contribute to the software itself.

Some say that this detracts from the role for which we were hired. I disagree.

The role of product documentation is hugely important to any company and its creation will always be the core function of a technical writer. However, as companies push to reduce timescales and costs, whilst ask that productivity is increased, the idea of a closely-knit team with a shared vision becomes all the more necessary. Integrating a Technical Writer into that kind of environment means that speciality becomes less of an issue, and everyone starts doing a little bit of everything else. This extends beyond the Technical Writer, obviously, but uniquely we span the divide between technology and user (application and customer) and so can start to play a larger part in the development of the applications themselves, and also lessen the impact on our own area of expertise.

As I stated in that discussion:

I’ve always presumed that the role of technical writing isn’t really about ‘writing’ all that much (these days) and is why I’ve pushed to change job and team titles away from “writing” or “publications” to “communications”. It’s a small thing, but I think it breaks the “document monkeys” label a lot of people still have in their heads.

What this can mean is that a Technical Writer needs to have a sufficient knowledge to be able to intelligently converse with the application developers, and a good understanding of the business and user requirements that are currently being worked on. Acting as a “user proxy” in early design meetings has the double bonus of improving the application being developed (as most developers have a tendency to think in terms of functionality, rather than task) and hopefully easing the burden on the documentation as the general usability should be improved.

A bold statement perhaps, but ultimately the long-term aim is to have a better grounding in the usage of the application for which you are writing documentation. Understanding the why, and the who, as well as the how, is not a new thing of course, but contributing to the team in a “non-document” way is the real benefit.

A lot of companies still view product documentation, and the technical writers who produce it, as necessary evils to be tolerated and humoured. Most technical writers are able to constructively challenge and change that perception and I’m certainly not suggesting that anything I’ve suggested is the only way to do things. But I do believe that, in software documentation, there is a growing call for more technically technical writers, as opposed to technical writing writers. Becoming the accepted user-advocate in your development team is one path to achieving this, and I firmly believe that it will enhance both your own career and the perception of our profession.

Additional links: TechWR Mailing List.

On switching

I received my MacBook some weeks ago, but decided not to post immediately and try to get a better feel for both the new hardware and operating system before posting my thoughts. What follows has been written up over the period of a few weeks.

It’s official. I am now cool. I must be because Matt said so, in a roundabout way admittedly, and in case you have no earthly idea what I’m blithering on about now, I’ll first refer you to this post, and then get to the point and confirm that yes, I am now the owner of a shiny white MacBook. I am cool.

As is my wont, I had spent some time researching, reading articles written by those who had ‘switched’, and compiling a small collection of free applications that I figured I’d need at some point. So, with several PDFs, a folder of software, and several AVI files (for watching on the plane), I was all set.

There are a myriad of articles and blog posts written about switching from Windows to OSX, and I’m not going to add to them, instead I’m going to attempt to give you how I feel about becoming the owner of a Mac, because that’s what it’s really about, isn’t it?
Read More

Damned lies

A boring post about website statistics follows. Feel free to scroll on down to the next post which may, or may not be more entertaining. What? You want a LINK to the next post? You lazy bugger…

Last month (or was it the month before?) I asked you for recommendations for a new stats package for this site. I had used Extreme Tracker and SiteMeter for a while and had always got inconsistent results, timeouts and generally have been unimpressed. Now, whilst I’ll happily admit to being a bit of a stats whore, long gone are the days when I care how many hits I get, it’s much more fun seeing where you all come from. That’s not to say the numbers aren’t useful… and they are most certainly welcomed.

As an aside, one of the casualties in my constant hunt for a decent stats package, not to mention my all too frequent changing of hosts (from … umm… something to LineOne, to Telewest, to 1and1, and now currently with 34sp) coupled with my non-existent archiving notions means that I have no earthly idea how many people, in total, have visited my website since it made it’s thunderous arrival on the interweb… ok, it was a tiny squeak, barely a ripple, a trend which continues today.

Taking some of your suggestions I have been running with StatCounter, Google Analytics, MeasureMap and MyBlogLog for a while now. Add in my hosts own stats and I’ve got far too much information to access and process, so let the cull begin! But first a little comparison to see which one best suits my needs.

Roll back to the first week in March (actually from the 27th February to the 4th of March) and here are the numbers each stats package gave me:

Package Unique Hits Returning visitors
StatCounter 1665 549
Google Analytics 1278 627
MyBlogLog 1144 NA
MeasureMap 989 ~445

I’m not including the stats offered by my host as they are HUGELY different and the terminology is a bit cack and I can’t quite figure out how to analyse it.. not that important anyway as I don’t need to do anything to collect those, they’re just there.

As you can see, the numbers vary quite a bit, and whilst Google Analytics and MyBlogLog are close enough on the Unique Hits, the difference between them and MeasureMap is pronounced, doubly so when you look at what StatCounter thinks.

It’s one thing being smart enough to collate data, but it seems it’s quite another thing altogether to be smart enough to display that data in a meaningful, easy to read way. I could spend hours deconstructing each package but I just don’t have the time, nor the energy. Suffice to say that:

  • StatCounter isn’t too bad, uses real english, and only suffers because it isn’t completely free (my, what a world we live in)
  • Google Analytics is awful. Slow to update, a complete bear to use and far too complicated for the likes of me. To be fair though, it’s not AIMED at the likes of me (although that’s no excuse for shoddy UI and meaningless terminology).
  • MyBlogLog strictly speaking this isn’t really a stats package per se. It’s primary aim is to let you see which links people have used to leave your site. And it does a bang up job of doing just that. Recommended.
  • MeasureMap – it’s clean, colourful and simple. Too simple really as it lacks weekly and monthly views, crucial if you want to see trends. But that should be balanced against the fact it is soft on the eye and easy to use.
  • 34sp Stats are achingly complete. Alas they suffer from meaningless terminology syndrome making all that data practically useless. Unless, of course, I am reading it correctly, and I DID receive over 20,000 visitors in the first week of March.

I should mention that MeasureMap was recently bought by Google, meaning that either Google Analytics will benefit from having Mr. Veen on board, or MeasureMap will benefit from having the backing of Google. Or both as both products are aimed at different markets.

Anyway, based on the above, I’ve dropped Google Analytics. StatCounter has become my daily stat check location, and I know that my 34sp Stats are churning away in the background if I want a really detailed look at things (I’ve not looked at them since before Xmas mind you). MeasureMap I’ll stick with for a while and see what influence Google brings, and MyBlogLog keeps on doing exactly what it says on the tin.


Until I spotted Performancing Metrics (which does look pretty good). Back to the drawing board?


Hello? Is this on?

Small blip there, apologies. I presume I missed a memo somewhere as it was definitely a server issue that affected a few other sites or was this one of those things I was emailed about months ago and have since forgotten? Most probably the latter so apologies again for the lack of warning.


As a Technical Author, I write software manuals for a living. The process of creating the manuals involves a fair amount of planning, information sourcing and research. Frequently I am writing the manuals at the same time the code is being developed, and it’s only towards the end of a project that I get to see the finished applications and compare them with the documentation. When that moment comes all hell breaks loose as usually my interpretation of a function (taken from a specification document) differs slightly from the implemented design in the UI. This is the way of things and I have no complaint at all as I’ve grown to accept that at the end of a development project, the tech author will always have a heavier workload than at any other time. I’ve worked in several companies with differing approaches to product development and it’s always the same. Universally constant.

I’m at that stage of the project right now. The only slight difference from the norm is that I’m currently working on six different projects, with manuals for two of them (the largest two) still being corrected and re-written. I’ve yet to start on a 250 page configuration guide, nor a 180 page system installation guide (these are large enterprise wide applications with many parts on different servers). And yes, I am beginning to hit the “mild hysteria” stage but have yet to make it full blown panic (I don’t think I’ll actually get there with this project as, for a change, all the information I need is available, I’m just lacking time to process it all).

Hang on, I’m breaking one of my own rules: Do not blog about work!

Suffice to say that whilst it may appear normal here, I feel very much like the graceful swan (ugly duckling?) of blogging. Posting glides smoothly onwards whilst real life is thrashing away under the surface. But then that’s no different from any other blog really, what you post is never a true reflection of your life, of your person, of your thoughts and emotions. For one, capturing such things accurately in writing is a skill beyond most, and if we blogged everything we did we would be churning out the most awful, boring and repetitive navel-gazing posts day after day after day.

Hmmmm, that feels a tad to close to the mark.

Never fear, posting will continue apace as I have plenty of ill-conceived draft posts that I’ll be dusting off and “pre-date publishing”, but I may be noticeably absent from your comment boxes (it’s normally Gert that notices, mind you, as she chases me from comment box to comment box). Of course, I’ll still expect you to keep me entertained with witty and pithy comments as, if nothing else, it would make a change.


The timesheet application we use at work has a web based front end. Unfortunately it only works properly in (you guessed it!) Internet Explorer. So last night, as I’d done a wee bit of work when I got home, I fired up IE and what did I find? It had been hijacked (browser hijacking is a manifest of spyware = not good).

A quick scan using Ad-Aware soon cleaned things up but it’s annoyance. Something I don’t have to put up with whilst I use Firefox.

Which brings me to mention that I’ve updated my original post about Firefox extensions. I’ve added one (Tab Clicking Options) and checked/correct all the links. Ohh and if you have come across any other “must have” extensions, please let me know.

I should also point out that there is a new version of the Opera browser now available. It has been simplified a lot, and whilst I think it’s a huge improvement over the previous versions (previous UI was clunky) I still prefer Firefox. Internet Explorer – Come in, your time is up!


I’ve often considered either switching this site or launching a new one which dealt with my professional interests and opinions, a la zeldman.

Trouble is I’m not sure how many people would care, and how to narrow down what I do so as not to tread into too many areas. Writing, Grammar, Evolution of language, UI design, HCI, web design and usability, educating users, etc etc – the list is endless. That’s one of the joys of being a Technical Communicator – you get to do LOADS of different things, unfortunately it is assumed that you don’t do any of them as well as a ‘qualified’ professional (except the writing bit that is).

Sigh, now I just need to get up enough motivation. Ohh and to check that I can post some stuff without getting slapped by anyone at work … lol.

I also need to start going to bed at a reasonable time and stop reading work emails at 11:46pm! And with that thought in mind, night all!