Blog Archives

Tech comm 2015 now on the map

Tech Comm on a Map now displays all the 2015 technical communication conferences that I’ve found so far. Take a look, and let me know if there are any more tech comm conferences, groups, businesses or societies to add.

Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. It’s a great way of seeing what we tech writers are up to, around the world. To find out more about the project, or to add something to the map, check out the project information page.

Tech Comm on a Map 2015

Empathy in UX design and development

A new theme is emerging in the UX (user experience) world: Empathy. Putting humanity into technology. Product designers want to ensure they have empathy with the users of their product. We in the tech world want to design for what people need and want, rather than for what’s new and shiny. I think technical writers can contribute to this discussion!

Last month I attended Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. A strong theme emerged at the conference: Empathy, what it means to be human in a digital world, creating an internet for humans… What’s more, this was a spontaneous emergence, not suggested by the conference organisers. It just happened.

My deduction was that this must be a “thing” in the world of web design and development at the moment, whether conscious or unconscious, whether generally known or just beginning to seep into our collective consciousness.

I’m wondering: how many other people have encountered this theme?

Since then, I’ve read a post by Georgina Laidlaw, entitled “Why Don’t You Have a Writer in Your UX Team?” (linked at the end of this post). Georgina was recently at the UX Australia Redux conference in Melbourne, where she noticed a “dearth of writers”. She follows that observation with an excellent and exciting description of the contributions a technical writer can make to a UX team: “five things a great writer knows better than anyone else in the room”. I’ll resist simply listing the five bullet points, because such a bald list wouldn’t do justice to Georgina’s post.

Georgina’s third point struck a chord: “Writers understand empathy“. She says,

Writers deal with emotion all the time. Even the writer of the blender manual is working to avoid frustrating or patronizing you, and to make things seem achievable so that you feel an affinity for the product you’ve bought.

Every professionally written item aims to communicate, and to do that, the writer needs to deal with emotion. They’re skilled at empathising with the target audience — the users of their words — whether that’s on a single-word basis, or a thousand-word basis.

I’d add these points: As technical writers, we focus on analysing our audience, thinking about how our customers work, what they want, and what they need. We get to see early version of the product we’re documenting, whether that be an app, an API, a piece of hardware, or another type of product. We exercise the product as a user would, in order to document its usage. Many of us interact with customers, via feedback on the docs, in forums, or in other ways. We see a different set of customers from those the product managers and marketing/sales teams focus on: we see and think about the “end users” (for want of a better term).

We can chat to the engineers, designers and product managers we work with, to share our insights. We can make ourselves known early in the design phase of a product, again to share our insights and also to expand our own knowledge of the product aims.

So, yes to Georgina and other UX specialists: let’s talk. :)

Here’s a link to Georgina Laidlaw’s post on SitePoint: Why Don’t You Have a Writer in Your UX Team? It’s well worth a read.

These links point to my notes on the four key-note presentations at Web Directions South: InterconnectedAn Internet for Humans too, Being Human in a Digital World, A Voice for Everyone.

A pic from me, for fun:

Empathy in UX design and development

Web Directions 2014 wrapup

This week I attended Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. I’ve blogged about most of the sessions I attended. This post is a summary of my impressions, with links to the more detailed posts.

This was a technical conference for technical folk. Yet the presentations that went down best were those that mixed the human side in with the tech. Those that gave techniques for handling situations and people as well as code. Those that included humour and people in the slides. Code is for people by people.

A theme stood out in the keynote presentations and many of the other sessions: putting humanity into technology. There’s a concern that technical design focuses on what’s cool and new, when it should rather focus on what people need and how users want to interact with their tech.

IMG_20141031_090244 (1)

The quality of the sessions overall was excellent. In particular, Sarah Mei’s presentation on day 1 gave me a lot to think about. Her idea is innovative and unusual: to analyse the way we make technical decisions, so that we can then apply the same process to the harder tech decisions. Jeremiah Lee’s talk on day 2, about what makes an excellent API, had some excellent nuggets of information that were particularly relevant to me as an API technical writer. I especially liked the bit about passive usability testing via analysis of existing data.

My own presentation was on day 1: Bit Rot in the Docs. It was a bit freaky – the sessions took place in a theatre, so I was literally on stage, with bright lights shining down on me and the audience in tiers of seats extending into the blackness.

Looking for more pics? Try Xavier Ho’s photos. There’s even one of me giving my presentation. (I’m in the fourth row of photos, third from the left.)

Here are my detailed notes:

A huge thanks to Maxine Sherrin and John Allsopp for the hard work and dedication they put into organising Web Directions. Thanks also to all the presenters and attendees. It was a great experience! Oh, and one final observation: The chocolate brownies were to die for.

Bit rot in the documentation

This week I’m attending Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. It’s a privilege to be here, and to speak at this cool get-together.

My session is called Bit Rot in the Docs. (The link goes to the slides on SlideShare.) The presentation looks at how documentation can degenerate over time, and some techniques for finding and fixing errors.

The very mention of bit rot will strike terror into an engineer’s heart. “Unused programs or features will often stop working after sufficient time has passed, even if ‘nothing has changed’.” (From the hacker’s Jargon File.)

Bit rot affects documentation too. Whether the cause be a changing environment, human error, or the infamous cosmic rays, we need to root out that rot. But should the technical writer read and test the documentation on a regular basis? That’s the least efficient and most error-prone way of detecting doc decay.

Instead, in this session we looked at the following techniques:

  • Automated testing of code samples.
  • Documentation reviews as a standard part of engineering team procedure.
  • Collaborative spot-testing.
  • Customer feedback.

For more details of the session, see the slides on SlideShare.

Bit Rot in the Docs

The DITA debate

I’m coming to the conclusion that there are specific types of content that suit a DITA environment, and that the converse is also true: DITA is not the best solution for every content type. (DITA is the Darwin Information Typing Architecture, an XML architecture for designing, writing, managing, and publishing information.)

“Well, duh,” you may say. :) I’ve never worked in a DITA environment, but I’ve attended two indepth training courses and a number of case studies that walked through successful DITA implementations. The most recent was at the ASTC (NSW) conference last week, where Gareth Oakes presented a case study of an automotive content management system that he designed and implemented in collaboration with Repco. The content is stored and managed in DITA format, and published on a website. (See my report on the session: Repco and DITA.) This was a convincing case study of a situation where DITA has succeeded very well.

In my analysis, the DITA implementations that work well are those where the content consists of a large number of topics, and where those topics have an identical structure. It’s almost as if you’re building a database of content. Good examples are catalogues of automotive spare parts, machine repair instructions,​ safety procedures, aircraft manufacturing manuals, and so on.

Apart from volume and support for a standard layout, this type of content has other requirements that DITA can satisfy well, including the ability to automatically build a variety of manuals by combining the topics into different configurations (via DITA maps) and multi-channel publishing.

On the other hand, some content doesn’t benefit much from such a highly structured storage format. Potentially, the overhead of a DITA environment is overkill and the costs may outweigh the benefits. If we have contributors to the docs who are not tech writers or developers, asking them to learn DITA or specific source control and editor rules can be a deterrent.

Dare I say it: Much of the documentation we write in the software industry falls into the latter category. Our topics tend to be lengthy, less uniform in structure, and more discursive than, say, an auto parts manual. API reference docs are an exception, but they’re auto-generated from software code anyway. We also don’t usually need to recombine the topics into different output configurations, such as different models of a car.

What do you think? Please contradict me. :) Do you have examples that gainsay or support the above conclusions? I’d love to see some examples of well-structured and well-presented documentation produced from DITA source.


Get every new post delivered to your Inbox.

Join 1,508 other followers

%d bloggers like this: