Tag: UI

bookmark_borderImprove the experience

Posted on

Recently, Tom suggested that:
if someone can figure out how to make help whallop the user with wonder and awe, it will be the creative innovation of the century. Once we begin to establish a standard and a precedence, people’s beliefs will change from feeling that “all help is useless and unimportant” to “the help at my company is exceptionally good and useful; I will explore it more often.”

And I completely agree.

But.

Whilst he goes on to list ways in which the future of online help may expand – personalized help, feedback options, audiovisual options and such like – I think that is only one side of the coin.

While, without a doubt I could work harder to improve the content offered as online help, I think technical communicators need to expand their view a little, step back and see a bigger picture. I’ve touched on this before, and it is by no means original, but ultimately we are at a point where it is beginning to be realised that the information provided with a product is a most valuable commodity. With that in mind, the time is ripe for what Tom suggests, a new way of presenting information is surely on the cards. However I think it’s wrong to limit it to online help or documentation alone.

I’m lucky that, presently, I’m part of a company that allows the Publications Team (MUST change that name!) to be part of the softare design process. As such I can see, from inception to release, the decisions and design thoughts that go into producing our software, and I influence them as much as I can. Making the on-screen text useful is one thing, the next step is to think “task task task” during any discussions on design. Developers, rightly, take a requirement and start thinking about how THEY can implement it, yet just by repeating the “task task task” mantra I was able to get them to start thinking about how it should end up, rather than the finite possibilities of how it could be implemented.

Just to clarify, I don’t sit at my desk and chant. Instead I tend to start discussions about our software with “OK, I’m [insert user type], what am I trying to do here?”.

I’m not ramming this down anyone’s throat, but my choice of language during discussions has started to rub off, resulting in some design decisions made because they were thinking about the task the user is trying to complete, not the fact that it would need to get info from database A and publish it to form B.

In response to Tom’s post, I said:

Perhaps the radical shift is helping to address issues without presuming that people will “end up in the help”. Instead of being the last resort we should be striving to stop people having to get to that point.

That said, if they do end up in the help then yes, it should have a sufficient “wow” factor without being useless. Ultimately, make sure the information they want is findable by whatever means they choose.

Being the customer respresentative, the interface to the interface, is part of that.

I once told a Technical Support Manager that, ultimately, the aim for my team was to put his out of a job. Obviously that will never happen as the myriad of platforms, hardware, and user issues that surround every software product couldn’t ever be documented (unless development of the software had ceased, in which case I wouldn’t be working for the company).

I guess the aim for a usability team, or anyone interested in improving the user experience, is to put the documentation team out of a job. If the interface is well enough designed that the user doesn’t get stuck, and if it includes enough information in the UI to help the user make decisions, then why would they ever need documentation? Of course, similarly to the Support team scenario, documentation will be required to support the less travelled paths through the UI, to help the user who wants to do things her own way.

And that is where Tom’s suggestions come in. If we can improve the information we provide, making sure the customer experience is maintained (bettered?), then they are more likely to come back.

bookmark_borderRecently Read

Posted on

Christmas looms large, and the days are “fair drawing in” as they say in these parts. I’m taking a couple of weeks off to relax and recharge, and no doubt to eat, drink and be (very) merry. As ever this time of year is pretty hectic, so here are few things that caught my eye over the past couple of weeks.

10 Word to avoid in your writing
A short list but the main point is to avoid gobbledygook. One of my pet peeves is the use of long words when a perfectly valid, shorter, word is available. The Plain English website has some excellent advice if you want to find out more.

No-one reads the help anyway

the next time you hear someone say, “No one reads the help anyway,” say, “Yah, no one uses Google either.”
This will lead to a puzzling follow-up question — What do you mean? I use Google all the time.
Then you say, What do you use Google for? To search for answers, solutions, and information when you have questions?

Like some of the commenters, I disagree with this a little. At a simple level it works, but there are flaws. However, as an opening gambit I think it’s a good one. It will make people stop and think, and once you have them thinking about it THEN you can explain the more subtle differences.

AuthorIT Yahoo Group Search
I’m listing this here so I don’t lose it again. Yahoo Groups are great but the search engine frequently falls over. MANY many thanks to Hamish for providing this resource, this is the kind of thing that makes the Internet great.

Building a successful web community

Do not assume that a community, particularly a successful web community, is easily built from the one ingredient of a shared interest – ensure there is also a goal or a purpose in the mix.

Very true. I know that some Technical Communicators are starting to thinking beyond user documentation, and the next step may well be to nurture online communities around your product. This article has some good tips, and I can vouch for them all having struggled to setup a Scottish Blogging site myself.

Technical Communicators and UI Design
Scott Nesbitt spotted an article about User Interface Design and a particular section caught his eye. It states that the documentation must be considered as part of the design, and Scott goes on to say:

“technical communicators need to get involved not only in the design and usability of an interface, but also how users will access documentation from within the interface.”

I couldn’t agree more with this, and recently I’ve been pushing my team to think along these lines, realising that we work with, and develop, “information” rather than “documents” meaning we need to have a greater sphere of influence.

To coin a phrase, we are the interface to the interface.

bookmark_borderWho do you write for?

Posted on

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.

bookmark_borderJack of all trades Pt. 2

Posted on

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_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_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.