Archive for Usability

Singing The Single-Sourcing Blues

Photo credit: Creative Commons
The following somewhat (but not entirely) fictionalised story commemorates a failed attempt to impart upon a decision-maker the benefits of single-sourcing technical content. 


Installation High

A 30-day free software trial of Madcap’s Flare software seemed like the way to go to get us out of the tired rut of our end-user technical documentation. This product’s offerings of single-sourcing capabilities included content tagging for advanced cross-referencing, sophisticated importing and exporting, team collaboration (with multiple levels of access for reviewers), and most of all, topic-based structuring.

Photo credit: MadCap Software, Inc.

When I met with the decision-making manager, his first question was why I needed 30 days. “Well”, I said as diplomatically as I could, “I don’t expect to be assessing the software 40 hours per week for 30 days. That’s just Madcap’s trial period.”

But that was just his warm-up because he seemed to have other plans in mind. “Before we start looking at new software”, he said, “perhaps we need to step back and assess what our users need.” Normally this would seem like a reasonable suggestion, but to date no interest had yet been shown about user needs, so why now? I suspected a delaying tactic.

Big Data for Small Minds

The manager offered to run some analytics on traffic for our Webhelp and maybe even send out a survey to all users so as to solicit their feedback on the documentation. The manager seemed confident that something would come of engaging our users, although I already knew that we had very little data on usage and that it would be very easy to draw whatever conclusions we wished from analytics. If this is the requirement needed to install a 30-day free trial of software, I thought, why bother?

“Have you thought of using WordPress”, the manager queried. I made a point of not letting my emotions show, but some part of the cheery recommendations I was planning died in that moment. “No”, I said but added quickly, “How would you implement a single-sourcing solution with WordPress?” The manager waned in his enthusiasm a little, so I took the opportunity to explain the problem/solution further.

“We have a large array of documents (user guides, training handouts, change management documents, release notes, and on and on) all of which are maintained in a way that creates great inaccuracies and much wasted time keeping track of revisions and duplicates.”

Magic Bullet Point

By mentioning the problem with duplicates, I thought I’d laid down a trump card of sorts, but the manager took it to mean that I was prey to some form of technical writer magical thinking.

“There is no software that’s going to prevent duplicates”, he said, “People, no matter how great the software, can still create duplicates.”

I had to pause at this. I wasn’t proposing a magic bullet. I knew full well that software has limitations. I needed an example to put him squarely in the seat of what the present system is like and why it isn’t working.

“When you drive down the road, there’s nothing preventing you from swerving your car into oncoming traffic”, I went on, “You can do it, but what’s preventing you is your agreement (coupled with myriad laws and cultural taboos) to play within the rules.”

“Of course, people can still create duplicates, but what we need is a set of tools that point us toward good practices rather than the current system (Word documents stored on people’s C drives) that get copied, and copied, and pasted, and then re-copied across the system in a way that’s prone to error. Then, if there’s a change to be made, who can find all the documents affected and change them?”

Enter Steve Jobs

The manager conceded my point, but then he went off in another direction to question the need for documentation—AT ALL!

“Do you have an iPhone”, he asked.

“Yes”, I replied.

“Did it come with a manual?”

“Well, yes it did”, I confirmed suspecting now where his questions were leading.

“Have you read it?” This was his turn to sound triumphal.

“No, I haven’t”, I said.

“You see!”, he erupted, “You have an iPhone and it has a user manual, but you’ve never read it!” He seemed almost delirious at this portrayal of software so intuitive it didn’t even need a user manual. Clearly, Apple in its magnanimity was providing user guides only as a form of self-effacing humility.

I thought it wise to choose my words carefully, so I paused. And then I said, “It’s true. Since I came to your software company, I have worked on the assumption that we all agree that there is a need for software documentation.”

Then I launched my final salvo.

“When your software is designed to Steve Jobs’s and Apple’s standards—that is, it’s so intuitive no user guide is needed­—I’d welcome the idea of dropping documentation. But I’m working with the system as it is now.”

It’s a Digital Life – Writing for the Web

When writing a blog (or any type of web writing), you are writing for an audience that’s fickle and distracted. There’s just too much information, so they flit about and if they encounter a challenge (such as poor organization, rambling prose, padded sentences), they bail. Web readers will not read your writing, unless it is written to their needs.

Web readers read differently:

  • They don’t read screens as easily as pages.
  • They tend to scan and forage for the content they want.
  • They don’t read in a linear fashion—they follow links and move about.

The general rule for web writing is to write shorter sentences, but little information is ever provided on how to write shorter sentences. The maxim, “Ride the horse in the direction it’s headed” is appropriate here. If you organize your information in a way that follows how people read, your blog is more likely to be read.

Perfect Contract

The Perfect Contract

I was contracted to provide technical help, which I would describe as The Perfect Contract. What was perfect about this contract was how much I was able provide because it mirrored my diverse range of skills and abilities. So much so, in fact, that the description of what I did reads almost like my résumé. This contract was a quick turn around – I was called on Thursday and had the majority of work completed by the following Wednesday.

Needs Assessment – 6 hours

The client was in the midst of an office-wide migration from Macintosh computers to Windows PC computers to be compliant with head office. I spoke with their IT Administrator to determine what operating systems were involved and what she thought the key issues were.

I discovered that some Users would migrate directly to PC computers and other would be on their old Apple Macintosh computers running Windows in a Citrix shell for several weeks. My training and materials needed to reflect that.

I explored their system making notes. I needed to know their systems well enough to anticipate a broad range of questions pertaining to both Apple Macintosh and Windows PC operating systems as well as the Citrix Shell. I concluded that I would be giving a lecture type demonstration to all staff using screen projections and handouts.

Create End-User Guide – 11 hours

At home, I created a complementary End-User Migration Guide aimed at both the full PC Users as well as the Mac Users now operating Windows in the Citrix Shell.

Topics covered included Understanding Windows 2000 Server, Using Word and Excel in Windows, Introduction to Outlook, Good PC keyboard shortcuts for Mac Users and how to navigate between the two environments.

Deliver Presentation – 1.5 hours

On Monday, I delivered a presentation to all available staff in their boardroom. I handed out my Guide and used a projector to demonstrate how their new computer environment would operate.

Following the demonstration I answered questions ranging from how to access old programs and files to security concerns in Windows 2000.

Provide Desk-side Support – 14 hours

After the presentation, I visited each staff member in person to help with specific questions or concerns. As with many offices, there was a broad range of skills to accommodate. Some Users had come from Windows backgrounds in other companies and were pleased to return to a Windows environment. Others had only ever known a Mac environment and verged on terror at the prospect of starting all over again with a new and unfamiliar operating system.

I took time to assess their individual needs so that I could provide service to even those who initially thought they didn’t require any support. For example, I showed some Users how to create mail rules to organize their email in Outlook, how to assign their favourite keyboard shortcuts to toolbars in Word and how to navigate and manage files in Windows.

I returned over several days to provide desk side support and re-iterate the initial presentation to those how had not been to the original presentation.

Design Corporate Logo 3.5 hours

An interesting spin-off of this contract was that the IT Administrator discovered that their corporate logo did not port over well from Macintosh to Windows and asked if I could redesign it.

My solution was to recreate their old logo using Adobe Illustrator and Photoshop and create both Web and print versions to suit all their needs. After one revision, they were pleased with what I created and the new logo now adorns their corporate letterhead and Website.

Conclusion

Although I have taken on more technically challenging contracts than this one, rarely have I been able to roll so many skills into one short contract. I welcome all other creative and diverse opportunities where my skills and abilities can be as well utilized.

And here’s what the client had to say

Thank you for providing [us] with Jason Hall’s services during their migration; the project is officially over. During the sign-off interview, [our IT Manager] said she was extremely satisfied with the work Jason did. (Despite me giving you such short notice!) [She] was particularly impressed with Jason’s ability to quickly resolve their logo migration issue. This would have been a huge problem for them to resolve but Jason did it within a day.

Thanks again for pulling the rabbit out of the hat. I look forward to working with you again.