I spent most of the weekend laying, re-laying, cutting and swearing at laminate flooring. I read the provided instructions, measured twice (hell, four or five times in most cases) but still it proved problematic. I re-read the instructions, googled a little and then, after some experimentation finally figured out what the problem was… me.

Well not just me, but my interpretation of the instructions which were a little vague in one key area. Namely, where to start. This is crucial as, most laminate flooring needs to be laid the correct way to make it possible to snap all the pieces into place. It’s a one-directional jigsaw puzzle, if you will.

The details here aren’t important, but what it taught me (for the umpteenth time I guess) is that documentation needs to be complete, unambiguous and for hardware related matters at least, a picture tells a thousand stories.

I keep going back to the assumed knowledge angle, and it rings true for this example. One of the forums I found during a frantic Googling session yielded a comment along the lines of: “The professionals know this but it’s not something you’ll find in the instructions”.

I have been guilty of this in the past. Presumption is the silent virus that can kill an otherwise excellent piece of documentation stone dead. All it takes is one presumption to render an entire document AND THE PRODUCT IT IS SUPPORTING, next to useless (or at the very least “problematic”). Introducing that kind of negative thinking at an early stage of the product lifecycle makes it very hard to undo.

Although that, itself, is a presumption. I’m presuming that most people only read the documentation when they are still novice users. So maybe that is another presumption that I need to work on removing.

Blimey, another week has flown past and, as ever a few things have caught my eye.

9 ways to gather user feedback
It’s often a struggle to get true user feedback on your documentation, Craig Haiss offers some suggestions to improve things in this area. Whilst I’ve tried some of these, and had heard of them all, it’s worth a look to jog the memory:

You can write the most detailed instructions in the world, but if they aren’t the instructions users actually want, you’re wasting your time. That said, how do you go about gathering feedback to flesh out your documentation?

Tech Comm Job to Job Title: Something Lost in Transit?
Ben Minson is musing on job titles and, as well as raising a giggle, ends up stuck. Job titles, as a way to convey what you do for a living, are important.

… the dictionary says one who documents is a “documentalist”—however, I’m reluctant to adopt a job title that includes the word “mental.” So this is where you get “documentation specialist.” The same goes for “usability specialist.”

It seems a little funny that, being writers at heart and therefore professional manipulators of language, some of the terms we pick for our field don’t easily translate into job titles.

I’m currently experimenting with the title “Technical Information Manager” which is a little OTT but seems to fit my current role, thankfully my company, like myself, isn’t hung up on formal job titles (they prefer that you, you know, get on with whatever needs done). So, what’s your job title?

Typography humour

Glossary of DITA terms
Bob Doyle is wondering if there should be a central, user-maintained, glossary of DITA terminology:

many DITA-related terms are not defined … They are simply assumed.
And some is insider jargon, like reltable for Relationship Table.
And there is no convenient alphabetical listing.
You can search for terms on the DITA Infocenter, but then you have to already know the term.

This got me thinking. If you have been toying with setting up a documentation Wiki, then this may be an excellent place to start. It might also throw up some interesting usage of terminology. Definitely something I’m going to have a stab at (well, I’ll add it to the list of things to try).

RoboHelp vs Flare
Interesting round up of posts and comments on this topic. If you use, or are planning to use, either product, give it a look.

And I’m done. Another week in the wonderful world of Technical Communications has gone, I wonder what next week will bring?

The timing of this post, and the announcement by the Cherryleaf blog that they’ve created a Facebook group for technical authors, is completely coincidental. However there does seem to be a genuine move towards online communities, or perhaps it’s just the latest fad?

It’s an interesting time to be building an online community, and I’m lucky that I can pull from the past ten years or so that I’ve had an online presence.

When blogging first started there were few tools available, but in a short space of time they started cropping up all over the place and these days there are many different ways you can post to your blog (as well as many different ways/places to host it). The same seems to be true of the current rise of “social networking” sites.

Places like MySpace and Bebo focussed on the network surrounding one entity, whilst FaceBook and LinkedIn focus on central groups, and finally services like Ning allow you to build an entire specialised community which can then focus in on central areas of commonality.

I have a LinkedIn profile, a Facebook profile and I’m a member of a Ning community, and for me they represent different things. Ohh and please don’t be offend if I don’t “friend” you on any of those websites, I do try and keep that sort of thing under control.

For me LinkedIn is, in essence, a smart contact manager that allows me to find other people related to previous places of employment or study, whereas Facebook is something I dip in and out of and which I primarily use to keep in touch with friends and other personal/social goings-on. Ning, specifically the Content Wrangler community, is very much focussed on my profession and is a good way to interact with my peers across the globe.

I’m wondering if my perception of these sites are common? The reason I ask is that whilst creating a group on Facebook or LinkedIn is very easy, perhaps the usage of such sites needs to be considered. There has been a lot of chat about companies starting to “lever” these websites, alienating users/customers. So it definitely isn’t just me that has a fixed idea about for what these websites should be used.

I’m in the midst of trying to build an online community for the technical users of our product, and I’m very conscious of the unwritten rules and presumptions that go hand in hand with how people act online, and which boundaries need to be respected. It’s a balancing act, that’s for sure, but a fascinating one.

A phrase I spotted online the other day rings true: “someone hit them with the Web 2.0 stick”. I’m a big fan of Wikis, blogging and online communities, and I think they offer some excellent ways to be part of the conversation, but perhaps we all need to step back a little and make sure that the tools we are using are the right ones for the job.

Re-reading the article I submitted to the ISTC Communicator magazine, I realise that my average day isn’t:

• particularly average at all
• a true representation of everything I’m involved with

I lead a team of writers so my typical day may not apply to everyone, and I also have a tendency to stick my nose in and get involved in other areas if I feel I can be of help. Simply put, if I hear someone talking about “information” my radar pings and I see if I can be of any benefit.

Other non-typical items include collation of Product Release Notes, my team proof-read Marketing brochures and website collateral, we try and monitor consistency in the UI of our customer facing product, and I’m currently in the process of creating (and managing) and developer community website. As an “unbiased” member of the development group I also recently facilitated our retrospectives.

One of the reasons I love this profession is that you can (and should?) be involved in many different areas. We have a unique view of the product and I guess my day is sculpted by that, although it is helped that we are a small(ish) company and have a small group of people thinking about the “product” as a whole.

I’m lucky that our company doesn’t have a traditional structure, with everyone encouraged to talk to everyone else regardless of role or level. It’s a little like a zoo sometimes, with a lot of noise and activity, but apparently that’s a good thing. It does mean I am involved in discussions that can be hard to be a part of otherwise, chatting to the Product Manager, Product Marketing and Sales, all of whom are saying the same thing, which in itself proves that things are working and that technical writers are a valid part of that discussion.

I’m curious to hear if others have the same opportunity; What other areas, outside of technical writing, are you involved in? And why?

Text Preferences Survey
What is the ideal text size to use on the web? What about line height and column (line) length? Most of the information in this area is based on print (at best) or anecdotal (at worst). A design agency in Brighton, Message, has decided to try and find out by carrying out a survey:

“Our goal is to publish a report that provides hard facts about what constitutes ‘readable’ text on the web … We see this report being of value not just to our clients and their customers but to web users at large.”

It only takes a few minutes to complete so go and take the survey.

Why software applications need product blogs and why they don’t get them
As well as having a very long title, Tom also hits on some points well worth considering if you are at all web savvy (and I’m presuming that, as you are reading this blog, you are). Most of his ideas are spot on but would require a lot of business process change, but I think they are worth picking up on:

I can think of six major ways product blogs can benefit users and project teams. Product blogs can …
- Provide a venue for product announcements
- Allow users to submit product bugs
- Allow users to submit feature requests
- Provide a roadmap preview for the product
- Enable a point of connection between users and project teams
- Provide a way to teach advanced tips to users

He also mentions something that I too have pondered, namely including RSS feeds in online help and somehow merging the two in a more dynamic way than before. Probably not much point in purusing that now but who knows what may happen in the future.

How to work better
A short list of simple, but powerful, advice which is applicable to everyone. Go on, there is at least one thing on that list that you could do better (or if you are like me, 3 or 4).

Subversion for writers
Entirely focussed on Mac OSX users, this has reminded me that we use Subversion at work and that I should really write up our process. Regardless of platform, the basic benefits of using a version control system can be realised with little cost.

What does it do? It manages multiple versions of a project in development. You check your project out of the repository, make changes and you commit those changes back to the repository. At any time you can view older versions of the whole project or of individual files, and revert to them, if the work done since was in error. You can make branches, which allows you to develop your work in two (or more) ways in parallel, and you can tag your project to say, at this point I met a certain milestone (eg: first draft, second draft, version sent to publisher X, version sent to publisher Y, published version, etc.)

Why would you choose to make something difficult to use? Are you deliberately putting barriers in the road? Or are you just forgetting the main reason why people pick up a document or manual?

Long ago, when I had just started out as a technical writer, I attended a course on designing for Print. It covered many things, from typography to layout and I still use some of the basic design rules I learned way back then.

Whitespace, choice of font, and hierarchical indentation can help make a document more readable. Clearly delineating the structure of a document without explicitly stating it as such, leaving visual clues to help the reader navigate the page (presuming you’ve covered the multiple navigation routes they’ll take to get to that page of information).

Such considerations will continue to become more important as more and more information is moved online, and is then available in a variety of media formats and devices. Structuring your content, and using visual clues to convey that structure clearly, will become ever more important.

At this point there starts to become an obvious overlap with usability, pushing technical writers to start thinking more in terms of the user experience than simple task analysis allows. Understanding the reasoning behind a user action will become equally important, and can be passed to development to influence the UI as well as directly impacting on how we present technical information in the future.

Beyond that I’m not sure where else this may take us but I do know that part of the reason I love this job is the cross-over we have with so many other professions/industries, and I can’t wait to see what is next over the horizon.

How many times in your professional career have you been asked to spell something, or asked if a word is hyphenated? How many times are you asked whether to use “that” or “which” in a sentence?

We are the grammar police, the word monkeys, and many of us revel in that role (if not the title). Typically we possess greater information about writing than anyone else in the company, and rightly so as it is the main focus of our job.

However I am trying to stop answering these questions directly, instead I’m trying to direct people towards an answer. The reasons are two-fold.

Firstly it’s always better if people learn things first hand, helping to break the dependency for the future. In other words it stops people relying on you to remember things for them. It stops you being asked the same question, over and over and over. That can be annoying.

Secondly, and this is a subtle point, it re-enforces the notion that ALL we do is write words, that all we consider is grammar and spelling, that all we bring to a development team are documents. I don’t know about you but that’s not the case for me, never has been and never will.

It’s easy to quickly hand out information when someone leans over your desk, but maybe we need to be a little more careful. As (typically) a minority group in a software development team we have to work hard to prove and maintain our value, so maybe we need to distance ourselves a little from such matters.