Hiring people with disabilities

I came across a strange section in a job posting recently. It appears to be a way to get around laws designed to prevent discrimination against people with disabilities.

This is listed in a job posting for a desk job, under "Qualifications":

PHYSICAL/MENTAL DEMANDS and WORK ENVIRONMENT

• Climbing: Ascending or descending stairs using feet and legs
  
• Crouching: Bending the body downward and forward by bending legs and spine
  
• Kneeling: Bending legs at knee to come to a rest on knee or knees
  
• Reaching: Extending hand(s) and arm(s) in any direction
  
• Walking: Moving by using the feet and taking alternate steps
  
• Pushing: To exert force on or against an object in order to move it away
  
• Pulling: To draw towards oneself, in a particular direction, or into a particular position
  
• Lifting: Raising objects from a lower to a higher position or moving object horizontally from position to position
  
• Repetitive Motions: Making substantial movements (motions) of the wrists, hands, and/or fingers
  
• Talking: Expressing or exchanging ideas by means of the spoken word; those activities where detailed or important spoken instructions must be conveyed to other workers accurately, loudly, or quickly
  
• Hearing: Perceiving the nature of sounds at normal speaking levels with or without correction, and having the ability to receive information through oral communication
  
• Visual Acuity (with or without corrective glasses): Close vision, distance vision and peripheral vision
  
• Sitting: remaining in a seated, upright position for extended periods of time
  

The ad also says:

EOE/Minorities/Females/Vet/Disability
Please view the EEO is the Law Poster which serves to inform you of your equal employment opportunity protections as part of the application process.

The EEO poster has this to say:

DISABILITY
Title I and Title V of the Americans with Disabilities Act of 1990, as amended, protect qualified individuals from discrimination on the basis of disability in hiring, promotion, discharge, pay, fringe benefits, job training, classification, referral, and other aspects of employment. Disability discrimination includes not making reasonable accommodation to the known physical or mental limitations of an otherwise qualified individual with a disability who is an applicant or employee, barring undue hardship.

This company appears to put the "PHYSICAL/MENTAL DEMANDS and WORK ENVIRONMENT" section in every job ad. Why would a QA analyst need to be able to crouch or put their hands over their head? Or walk, even?

Title dropdown list

I encountered this bizarre dropdown list today. And it's required!

Usability - Talking the talk and...

Two years ago at the Fluxible conference in Kitchener, I attended a talk by James Wu, lead tablet designer at Kobo, called "Rethinking the Tablet UX". I was really taken with the talk. I even wrote a blog post about it, here. It made me think that usability at Kobo was pretty darned advanced.

Yesterday I bought my first ereader, a Kobo Aura HD. In many ways it's a great device, and I'm not blaming James Wu, but OH MY GOD THE USABILITY SUCKS. It boggles my mind. The device is not unusable, and I'm sure I'll get used to it, but there are so many little things that are egregious bad practices. The incompetence is breath-taking. Take, for instance:

You can't read your Kobo while it is recharging over USB. Before unplugging the cord between your computer and Kobo, you have to click an Eject icon in the desktop app. This is a terrible constraint from a usability standpoint. In fact, after being reminded approximately eight million times, I forgot to click it.

During setup I repeatedly landed on pages with only one button: Eject, even though my device was still charging and still being configured.

On the device, there's a warning saying "Please eject your eReader before unplugging your USB cable", but it doesn't say how to eject it. You can't do it from the device. You have to open the desktop app and click Eject.

The repeated warning about ejecting made me think I'd damage my ereader if I pulled the plug without ejecting, but eventually I found, on a web page, that the reason for ejecting is that otherwise you might lose data. But there is no help whatsoever on what data you'll lose. Your last download? All downloads in the session? Does it matter if all you did was recharge, or if you use WiFi? Is there an auto-save? Can I recover by resyncing? For the love of god, give us a hand, Kobo!

Only some of the icons in the Kobo desktop app have tooltips. For others, you just have to hope you won't do something unintended... then click and try to figure out what it did.

The Kobo desktop app has no help button or link to help.

The official user guide (which I found through a google search) is in PDF format only. The table of contents aren't hyperlinks. The pages have no page numbers. The headings aren't registered as headings so you can't open a bookmarks pane on the left. There is no index. When you copy text out of the guide, spaces between words become either tabs or carriage returns. (I found the user guide so unnavigable that I tried to create my own subset of topics I needed, but the formatting issues prevented me.) The content is very sparse and mostly describes the UI.

The getting started guide is printed in eight languages simultaneously, and contains exactly 54 words in English. It's useless.

To get started, I downloaded a few free ebooks from the Kobo site, but when I tried to open them I got an error that they were Adobe Digital Editions and required special software. The user guide mentions Adobe Digital Editions and provides a link to Adobe but the link is broken and there is no information about how to set it up on my Kobo. Eventually I found an article on the Kobo site that explained what to do. I'm still looking for information on how to install Acrobat Reader on my Kobo. Why is installing this software not [an optional] part of configuring the device???

When you buy an iPad (I have heard), they start setup in the store and the whole thing is ready to go by the time you get home. When you buy a Kobo, it comes with a dead battery, completely unconfigured, with a difficult and poorly documented setup process. I know there's a limit to the amount that can be done without a dedicated retail outlet (although I bought mine at Chapters), but Kobo is too far at the other end of the spectrum.

I could go on and on. Really. This product has an awful out-of-box experience. The documentation is a nightmare. When I look up Kobo on LinkedIn, I see a ton of people with UX in their titles, and lots of descriptions of user research. What in god's name are they doing?

Case Study: Disruption

Back in the 1980s I worked for a computer timesharing company. We had a large mainframe computer with a proprietary operating system and a corporate internet with nodes all over the world. Our customers used dumb terminals (a monitor with a connection to a mainframe) to do their computing work, and they paid by the minute. We had the world's largest (or second largest) corporate internet, and a large customer base of companies such as insurance companies who needed more processing power than was available elsewhere.

My division, Data Services, provided databases that users could access, and they paid based on usage (so much per data point). Data Services provided statistical software that ran on our mainframe and could be used for the timesharing fee. We provided enormous economic and financial databases, but really shone in the areas of energy and aviation.

My colleagues were extremely bright and forward-thinking and we were in a constant state of innovation, but in many ways we were always a few years behind the rest of the world. When I started there in the mid-80s PCs were already widely used in business, but my terminal had no monitor, just a wide paper feed: all input and output was recorded on paper. After a while we upgraded to dumb terminals and then to PCs. Our customers used acoustic couplers to connect (a kind of modem where you put the handset of your phone into connectors), and I worked on helping them move to faster modems. I attended endless meetings where we grappled with alternative ways to deliver data to customers, such as floppies, CDs, and quarterly downloads. We fretted over ways to modernize our pricing, and one of my jobs was to create pricing models to estimate the effect on revenue from alternatives such as subscriptions, or unlimited and report-based pricing. It was a bitch teaching our workforce the basics of PCs, and transitioning our developers from APL to C++.

As data storage and processing power exploded, the basic business of the company, computer timesharing, became anachronistic. Eventually the company was purchased, cherry-picked, and mostly shut down. But in a lot of ways the company was ahead of its time. We had software that changed traffic lights for emergency vehicles decades before others produced anything as sophisticated. My division, Data Services, was a leader in value-added data and statistical analysis software. We were achieving good profits and growth right to the end.

When I was eventually laid off I was traumatized. I had been so invested in my work that it was like slamming into a brick wall at 70 mph. That was 25 years ago but in some ways I haven’t recovered. I worked at RIM when it became clear it was failing, back in 2012, and couldn't stand the idea of suffering through another slow death: I jumped ship as quickly as I could, but for a year I maintained an almost obsessive watch on the company, checking the stock price and reading the analysts and pundits daily.

My experience with a failing company led me to pick up Clayton Christensen’s The Innovator’s Dilemma some years ago. It seemed that we fit his thesis (PCs disrupted the timesharing business). It was (and is) important to me to understand why bright people - who realized their predicament, had the will, and had the resources to change – couldn't make it. Christensen’s contention that you can’t make substantive change from within, but need to start a new subsidiary, is pretty compelling.

Despite its strengths, the book didn't pass the smell test for me. It is too simplistic, too dogmatic, too anecdotal, and inappropriately universal. Christensen seemed most intent on proving that we have to throw out old values and instincts, that we have to adopt a new way of doing business that is even more ruthless and cut-throat than before. It seemed more like propaganda than theory: another phase in the right-wing attack on civilization, a new libertarianism for the private sector. The smartypants premise is that the best and the brightest must admit defeat to the small and the weak. The innovator’s dilemma is that “doing the right thing is the wrong thing.”

I don’t have a copy of the book and I don’t want to critique it, but I am energized by Jill Lepore's fantastic piece in the New Yorker (link). This is the first in a planned series of articles about what Lepore calls the disruption machine.

On indexes

I love indexes. I love using a good index and I love creating a good index. All this dates back to my childhood and cookbooks. The Joy of Cooking, in those days, had an index that was truly a joy. The person who created it (perhaps Mrs. Rombauer herself) knew cooks well enough to know what they would be looking for, and gave us a long, redundant, gloriously usable index.

Mastering the Art of French Cooking, on the other hand, had an index created by a moron. Although Mastering the Art was published in two volumes, Volume II had a combined, color-coded index that always threw me. Worse, there was a confusing use of French and English terms. Look up mustard and you found some entries; look up moutarde and you found others. I bet that Julia Child passed off the indexing responsibility to a flunky.

Every couple of years Mrs Rombauer published a new edition of The Joy and she revised the recipe selection, the recipes, and the index. It was a true process of continuous excellence. Mastering the Art, on the other hand, has not been revised, except to update for new equipment (such as food processors) and changes to ingredients.

It is not uncommon for doc managers to task junior writers to index the works of senior writers. It's not just that you need to understand content to do a good job indexing it; it's also that indexing is a good exercise for a writer to do as part of their content creation. It's a second level check of your content organization. It's also a way to implement reader issues you might be aware of. For example, if you're documenting MS SQL Server and you know that some readers will be more familiar with Oracle, you can index some Oracle terms such as System ID for Database Name.

There is a growing movement in the tech writing biz that indexes are unnecessary. I see the point for online help; numerous studies (including my own) have shown that readers prefer to use Search (and in fact, they often prefer to use Search in Google rather than within the doc). But if you publish PDFs that your readers will print, then you need an index. And if you're going to have an index, you should make a good one.

At a conference years ago I attended a lecture on indexes given by an academic. His theory was that indexes should train the reader to use correct (his idea of correct) terminology. The example he gave was of a home first aid guide he had once worked on. He declared proudly that he had changed the index entry for "collar bone" to "collar bone: see clavicle". I don't know what he said after that because I walked out.

DITA in times of contraction

When Pubs managers decide to move their doc content to DITA, all they see is the savings. It's ROI, ROI, ROI. "You have to spend to save," they argue, and they often start spending hundreds of thousands of dollars on software purchases, training, and non-writing personnel. All that's fine when a company is growing and has loads of cash, but what risks are Pubs managers exposing themselves to if the company hits bad times?

As I have argued before, in many cases DITA doesn't so much save money as redistribute it. Where before you spent the lion's share of your doc budget on salaries for writers, now you're spending the most money on tools developers, information architects, editors, and software.

I'll give you an example: I once worked in a DITA shop where a team of 11 writers was overseen by a manager, three team leads, three editors, and two information architects; and it was supported by nearly a dozen tools developers. There were almost twice as many non-writers working on the documentation as writers (and yet writers had to fill out complicated forms for the editors, as well as project-manage the localization of their docs). The CMS was enormously expensive, and then the CMS vendor end-of-lifed our database so we had to spend a pant-load on a new one, including two years of research, planning, tools redevelopment, migrating, and tweaking the migration.

In a DITA shop, teams become complexly interdependent. Much effort is expended on assimilating writers so that they give up their holistic approach to writing, and accept their role in a DITA production line that starts with information developers; relegates writers to the role of filling in content in designated, pre-typed topics; and ends with editors. As it was explained to me, the writer must learn to pass the baton. DITA proponents argue that writers who can't assimilate should be fired.

The CMS and publishing tools are enormously complex so that nothing can be published without the help of a large team of tools developers. In addition, the complex new processes and corresponding bureaucracy require training (and hence trainers) before new writers can become productive.

Now imagine that the company has a profit dip and needs to cut costs. Who and what is expendable?

Before you had a team of writers, and if the company got in trouble you could lay off some with minimal impact. But now, if you have to contract your Pubs department you're in a pickle. The information typing process relies on so many non-writers that it seems inevitable that when companies are in decline, a DITA shop is going to have to give up more writers than a non-DITA shop.

That fragile CMS doesn't run itself, and keeping it going requires expert skills: you're going to have to keep most of your tools developers unless you want to give up publishing documentation altogether. It's probably not possible to give up the expensive maintenance plan for the CMS, either.

Your complex processes are going to continue to require the trainers, team leads, information architects, and editors.

In short, you're left with an expensive behemoth that can't be easily dismantled... unless you decide to ditch DITA altogether and migrate to a simpler solution.

The risk of DITA is fine when there is real justification for adopting DITA: when there is real need for reuse, when translation savings can't be garnered by a simpler alternative like Docbook XML or Madcap Flare, when you absolutely need to enforce strict information typing on writers. The problem is that nearly all outfits that are adopting DITA do not have that real justification. They're wasting money on DITA, and that could get them into trouble when the cash stops flowing.

Helping developers write better API references

Several years ago I gave a presentation to developers at my company about how to write better API references. The goal was to help developers who produced public APIs to write code comments that would be more useful to the mobile app devs who used the APIs.

I started with a quote from senior management about the importance of the API references to the success of our products. At this point and throughout the presentation, I wanted it to be clear that I wasn't just some tech writer spouting off about how to do things: this initiative was important to development management. I constantly threw in quotes from development managers (using their names) to support what I was saying. (I couldn't go so far as to say there was an integrated initiative because there wasn't.)

Next, I sketched the current Pubs team initiatives to improve documentation for the mobile app devs: new web sites for doc delivery that made it more easy to find and use the content; new feedback mechanisms; research of what the app devs wanted; and developer outreach such as the presentation I was giving them.

On the subject of research, I described some recent work I had done. I had gone to a developer conference and conducted a focus group, as well as six round-table discussions; collected questionnaires; and done dozens of usability tests with developers. I had attended a hackathon where I interacted with participants, learning their frustrations and successes. I had also attended a Developer's Day where I talked to prospective app devs about their backgrounds and their interest in using our APIs.

My main take-away from that research, I explained, was that mobile app devs want development to be easy. One of my bullet points was, "They are looking for information that is complete, simple, easy to understand, quick to use, and easy to find." This may seem obvious, but most developers seem to assume that app devs don't want to be told too much - that they can figure it out. In my experience, all too many technical writers in development documentation make the same false assumption. What app devs say is: Spell everything out! Tell me how to do it! As I explained in my presentation, three-quarters of the app devs I talked to were working on multiple platforms, not just ours.

Next I shared some personas of mobile app devs. These were not personas that I had made up, but that I had got from senior development managers. (As I have argued before, I firmly believe that personas should be prescriptive rather than descriptive.)

Finally I got to the point where I could define what a public API reference is, and show some examples from our company. I criticized our current API refs: it was too difficult to create mobile apps with our APIs; app devs were complaining; we had acquired a reputation of not being developer-friendly; the API references were a major source of info for technical writers, so the rest of the documentation was suffering; we were getting too many support calls.

I showed an example of a really bad page from one of our API references and explained what was wrong with it. Then I showed them an example of a really good page and talked about why it was so useful to readers. That led into an interactive session of about 15 minutes where we looked at API references and discussed how to improve them. Although there were about 100 developers in the room, the discussion was lively and very positive.

The rest of the talk was guidelines to improve our processes going forward. I defined responsibilities:

• API developers: Document all the elements of the API as comments in source code.
  
• Tech writers: Review the API reference to help with wording, fix typos and grammar, and note missing content.
  
• Both: Tech writers collaborate with developers to add content and examples.
  

I told them that when they started to write code comments for public APIs, they should ask themselves: What is it? When would this be useful or necessary? Why would app devs want to use it? How do they use it? I said the The API reference should explain: every class, method, parameter, etc; side-effects (what this code will affect and vice versa); and assumptions: always think of the customer. Imagine someone who is busy, doesn’t want to spend a lot of time figuring things out, hasn’t immersed themselves in our environment, just wants a quick answer.

After that I described some of the reasons our company had ended up with poor API references, providing a solution for each issue. For example, one solution was, "Ensure that the API reference is a deliverable. Make the API reference a product requirement. Add the API reference to the Definition of Done."

In the question period at the end, many of the developers provided even more ideas for how to make things better going forward. I ended with a quote: “Poorly documented code? Chances are the problem lies not in your programmers, but in your process.”

Give them what they want - or what they need?

I've been catching up with discussions in LinkedIn groups today, and I keep running into this quote by Andrew Brendenkamp:

Content Strategy should be about who is my target audience and what content do I need to give them to win them (and keep them) as happy customers.

It's a good quote - no dissension here - but it makes me think that there is more to meeting customer needs than making them happy. Documentation, like usability in general, is a background function: the foreground function is that the user can use the product.

So you might produce beautiful documentation that garners raves from readers, but it doesn't actually do what it's supposed to do. For example, readers might not realize that you've omitted key information; or that they could have learned what they needed in many fewer words; or the people who find the documentation think it's brilliant, but most people can't find it. Of course there's still value in wowing readers, but that is secondary to the main purpose.

Don't get me wrong: writers need to be close to the business. They need to consciously meet business needs. But business needs might be a bit more subtle than "happy customers". And metrics that focus on the easy targets might miss the mark.

Musings on tech writer interviews

Google recently announced that it's ceasing its practice of asking brain teasers in interviews. Their VP of People Operations said they'd stop asking things like, "How many golf balls fit into an airplane?" and "How many gas stations are in Manhattan?" and “How would you weigh your head?”

I haven't interviewed at Google but I've been asked some pretty goofy questions. I was once asked "If you were an animal what kind of animal would you be?" (to which I said, "I don't have an answer for that"). I once interviewed for a financial analyst job at Wood Gundy and was asked what country clubs my parents belonged to and where our cottage was located. (I had no answer to that, either.) I was once asked no questions... the interviewer just talked and talked nervously and then offered me the job.

Mostly, though, I've had pretty good experiences being both interviewer and interviewee. I think the trick is to make a connection and exchange information frankly. That's why I don't like interviewing unemployed applicants, cruel as that sounds. If someone has to quit a job to take a job, then they will be more interested in ensuring it's a good fit on both sides.

I've always thought that things said in interviews should be considered as semi-contractual. If an employer tells an applicant they're concerned about the applicant's short durations at recent employers and asks if they'll stick around - and the applicant says yes - then the applicant has an obligation to stick around - at least two years, unless there's something really wrong. If the applicant says he wants to move up to manager within a few years and the employer hires him, then there is a presumption that he will have the opportunity to advance, given good performance and favorable conditions at the company.

I think it's folly to ever hire a writer without administering a writing test. Having writing experience, even senior experience, doesn't guarantee that the candidate has any writing chops. The test can be as simple as having the writer edit a poorly constructed paragraph or writing a procedure to perform a simple task. Similarly, it's important to ask questions that validate skills... I once interviewed a woman who said she was expert in SQL but despite ten years documenting databases, she didn't know how to retrieve data from a table.

Fluxible 2013: Recap

Last year I wrote a series of detailed posts about sessions at the Fluxible conference in Kitchener, Ontario. This year I was a volunteer at Fluxible #2 so I was unable to take as good notes. I had to keep dashing out of sessions to put drinks on ice and so on. But I got the gist of things and in some ways, it was an even better way to attend the conference, as I was less lost in the weeds and reflected more on the big picture. So here's my scattershot and/or 10,000 foot view of what was going on at this year's Fluxible.

Warning: I am basing this post off my notes, but I can't guarantee that I'm representing every speaker completely accurately. A particular problem may be omissions since I was not always in the room.

The conference started with a series of five minute talks. Steve Baty started us off by talking about the nature of innovation - from the old meaning of the word (insurrection, rebellion) to its meaning as incremental improvements such as those practiced by Toyota, which constantly pushes ahead with an empowered workforce and small steps in manufacturing and design that enable it to make the best cars. The next speakers talked about disruptive change requiring a new attitude. We were reminded to not focus only on users, but to also research "near users" (people who use a similar product) and non-users.

Trip O'Dell talked about the changing demographics of mobile users and how we need to adjust our thinking. He said previous heuristic expertise is becoming obsolete. He warned that designers are becoming more distanced from their users - up till now, it was "20 year olds designing for 20 year olds": designers tend to be rich, educated, tech savvy, and early adopters of technology - what he calls "high agency users". But now, increasingly, mobile users are in poorer countries, and users are often poor, less educated, and functionally illiterate. He calls these "low agency users". These users aren't just in developing countries: he said that 15% of North American adults are functionally illiterate too. Italy and Mexico have especially high percentages of low agency users.

Low agency users are usually not of low intelligence: we just need to show rather than tell. The main things that need to change are the text-based nature of UIs and icons that are rooted in our culture.

O'Dell pointed out that the current trend in UI design, flat icons, was inspired by transit language in airports: those icons pointing to baggage pickup and so on. Those icons are big, bright, clear, and meaningful across cultures.

He also noted that a new trend among apps for low agency users is playfulness. For example, the Chinese app WeChat, which has 550M users, has a feature where you can shake your phone to connect to other people who are shaking their phone at the same time.

"Low agency countries" tend to have an ownership culture, where people want to own rather than rent. Netflix would not do well there.

Diana Wiffen of Quarry Communications talked about how to design winning digital experience design strategies.

Here are speaker Konrad Sauer's notes on the conference: link.

Cell phones > Smartphones > Superphones > ?

Just fooling around here, but with the rapid evolution of smartphone technology, you have to be wondering where it's going.

Earlier this year we learned of an imager chip that lets mobile phones see through walls, clothes, and other objects.

With Square, we see an evolution to peripheral devices that free consumers from the sales cycle of phone manufacturers. (Square sells a little piece of hardware that turns phones into credit card readers.)

And of course, wearable phones are here, currently as glasses or watches.

But we still seem to be just on the cusp of fundamental change. There is emerging technology that lets finger and hand gestures do many things, that lets brain power direct objects without physical intervention, that replaces phone screens with public viewing areas. In five years the paradigm of typing on tiny keyboards and peering at tiny screens may seem ludicrous. More interestingly, there may be a fundamental change in what we do with our mobile devices.

I don't pretend to have any clear view of the future, but I wonder what the social effects will be. Economist Tyler Cowen worries that technological change will kill the middle class, although he doesn't argue the case very convincingly.

The internet was built on porn. More recently, the economic driver of technological change appears to be advertising and its insatiable need for more and better data on consumers. Game developers even talk about the importance of "digital exhaust" - making gold of information previously thought worthless, like how long certain demographics of player linger on a level in a game.

What will happen if data becomes available to everyone - if, just as free access to the internet became seen as a right of humanity, access to data becomes a right? The killer apps of the future could be ones that mine, analyse, present, and use data. That seems like a future I can get excited about.

* * *
This post is cross-posted on my other blog: Yappa Ding Ding

The lesson of databases: use only when necessary

The current CIDM newsletter has an article about content management systems: Why do organizations hate their content management system?

The article is scathing about companies that make bad purchasing decisions, and scathing about CMS vendors that make difficult, bloated products.

But the article is missing something important. The fact is that relational databases are notoriously difficult to use. I spent over ten years documenting databases, so I've seen some of the messy innards first hand. You don't just buy an RDBMS and then figure out how to use it. You need Database Administrators with a lot of skills. You need to make an ongoing investment of money and time just to keep the thing working.

When I worked in the IT department of a large financial firm, there was a prohibition on databases. We used Excel in very sophisticated ways. We transferred millions of text files a night. But we avoided RDBMSs at all costs. Apparently the company had been burned badly by a database implementation and was unwilling to try again.

The CMSs used by doc teams present extra challenges. At one DITA shop where I worked, our CMS vendor decided to deprecate documentation use of their CMS and end support for our application of it. That meant that we had to spend an enormous amount of time and expense to choose a new CMS and get it set up. The cost must have been in the hundreds of thousands of dollars, none of which was figured into the initial ROI for moving to DITA (which we had done just a couple of years before).

I would admonish documentation departments to avoid using a CMS unless they really need it. As with DITA, it makes no sense to take on the enormous expense, steep learning curve, extra manpower requirements, and ongoing hassles - unless you really need it. "Really needing it" means that simpler options won't work for you. The complexity of reuse in most doc departments doesn't come close to justifying the enormous expense.

Documenting customer research

All too often, in-house customer research efforts are ineffective because the results are poorly documented. My rules of thumb are:

• Write up your results as soon as possible after conducting research. No matter how good your notes or recordings, you had "ah-ha" moments that you won't recall later.
  
• Write your results in an effective way. Make the important points resonate. Don't bog down your report in useless details. When writing up one-on-one interviews, think of it as writing personas. Think of it as telling a story.
  
• If you archive your results in a PowerPoint presentation, make use of the Notes feature to fill in all the information that you impart verbally. Think of the deck as an artifact that will be read on its own.

When I started working at one place, I learned that my manager had done a round-table discussion with customers the year before. I asked if I could read her results and she said that she hadn't written anything because she recorded the session. I listened to the recording, but the way the mike was placed I could only make out what she was saying: the customers were largely inaudible. It was clear that I was the first person (including her) who had bothered to wade through the three hour recording.

This recording-in-place-of-report seems to be a common problem. Recordings are supplemental to reports, not a replacement for them. Whether audio or video, recordings can be very useful when snippets are excerpted and presented. They are also hugely useful for writing reports. But in almost every case that's the end of their usefulness.

I have frequently found that the only report of a research study is a PowerPoint presentation, with lots of cute photos, lots of headings, and virtually no results.

At the other end of the scale are the faux scientists who write hundred page reports filled with large pie charts, with numbers reported to four decimal places (NO decimal places, please!), and a complete lack of understanding of how to report results of research where the sample is not representative of the population.

Even the most dismal interview can be useful if the results are well-presented. This isn't about window-dressing. It's about ferreting out what's important, and as with most things, it requires hard work to be successful.

Documentation as web sites

Those of us who write online documentation have an opportunity to move beyond the old book style of technical writing. Instead of writing books, we could start to think about whether we can present our documentation as web sites.

Instead of an opening page that has the date and a copyright notice (or whatever your HTML opens to), you could create a web page that is interesting and engaging, containing:

• A mix of types of information that draws people in and makes them want to read: a section on samples or case studies that are interesting to read through; a section of videos; and so on.
  
• Subtle but consistent and informative use of metaphor, such as visual clues that complement navigation.
  
• Quality art/photos that create a mood (not icons or clip art).
  
• Playfulness, creativity, and a focus on making people want to read the site.

When architecting doc web sites, I'd like to see writers considering good web site design principles. For example:

• Creating headings that use dynamic action verbs; headings formed as questions; and intriguing section titles such as "Try me".
  
• Chunking content based on reader needs (such as new/not-new, inexperienced/experienced, or UI/API), rather than organization by typical content-based chapters.
  
• Providing a seamless mix of content from all sources.

I haven't mentioned providing the opportunity for reader participation and feedback only because I think we're geting a good handle on that in the industry, and it's a given.

It's vital to note that none of this should be frivolous or have a marketing bent. None of this should feel like a bells-and-whistles approach. All of the effort should be focused on helping readers absorb and retain information.

The site should first and foremost be informative, and it should contain reference materials, numbered lists, detailed conceptual info... but content should not be included just because it covers everything that could be said. Content should be included only when it's needed by readers.

The whole thing could be written in topics and single-sourced into both the web site and a more standard structure in a PDF. Single-sourcing could also be used to repeat content in more than one place on the site.

There are problems to overcome with tools and with browser support. There are possible pitfalls: we don't want to create something that's busy, causes navigation problems, or is annoying. But I think this could be done.

Speak French?

Cirque du Soleil is advertising for a technical writer. They call the role "Documentalist".

Building an onion

When I approach a doc set that needs a lot of work, I think of my job as building an onion. That is, creating successive layers of quality. As I build my layers I learn the doc set and the product, making the next stages possible.

The first layer is typically the result of a copy edit: remove typos and grammatical errors.

Next, work on consistency. Start to revise terminology and wording conventions (and build up a style guide). Ensure the writing is active voice, second person, present tense. Read the doc critically, thinking about the suitability of the content for the target reader.

At this stage research is required: talk to managers, product managers, developers, customer support, and customers. Look at how competitors handle similar areas. Read Wikipedia articles for background. Read the standards that your product is based on. Read analyst research for your market. And so on.

Revisit your terminology decisions, and start to formulate a clear picture of your target readers.

Create a list of problem areas in the doc set. Prioritize them.

Continuous improvement

In my many years as a tech writer, I have seen a lot of truly awful docs. The reason was almost always the same: the doc was needed in a rush, and then nobody ever went back to make it better.

Even with well-planned, carefully written and edited docs, there should always be a process of improvement. All too often there isn't. Worse, groups that have CMSs often have highly-prescribed workflows that completely omit the need to tweak the doc after it is released. The assumption is that once released, the doc is finished. Perhaps they also worry that the company will incur higher translation costs if writers are allowed to polish published topics. But the way I see that kind of workflow is this: the workflow accounts for everything but quality. If it's a highly-prescribed workflow, you have pretty well ensured that you won't get quality.

Why should docs be revisited and continually improved? Many reasons.

Writers are continually learning new things about the product, technology, users, and how everything fits together. Frequently, we don't really get it when we write the first version of a doc, even though we think we do at the time.

Also, things change. When you wrote that you recommend Flash v9, that was correct, but now Flash v11 is out, and you need to change the wording to "Flash v9 and later" - or whatever is the case. When you explained what a Ribbon is in a UI, ribbons were new, but now we've all migrated to Office 2007 or later and we don't need those long explanations in every task (are you listening, Madcap?). When your product first came out, Product Management wanted to focus on a certain module, but now the focus has changed. And so on.

There are always errors. It's inevitable. We can't ever assume that the docs are absolutely correct and complete - we should periodically be checking them, and preferably do a thorough review every so often. Readers notice when the same error persists in release after release, and it doesn't give them much faith in your company.

Finally, it is difficult to be fully objective while writing something. Going back with a fresh eye will always result in seeing things that could be said better.

There is a sentiment that I see in a lot of doc managers, writers and blogs that quality isn't all that important. All too often, doc departments prioritize things that don't matter one iota to their readers. But content is king: helpful content and good enough navigation that readers can find the content.

DITA and the future of tech writing

This post is part of a series of posts that question some of the claims made about the benefits of DITA adoption.

DITA is designed to work with a CMS to create a fully structured tech writing environment. In a full DITA implementation, the process of creating technical documentation is fundamentally different from what is done in a traditional writing department. There are so many variations of tech writing processes that it's impossible to describe either the non-DITA or DITA structure accurately, but (with some trepidation), I'll take a stab at it...

In a traditional setup, at least for documentation that requires a fair amount of specialized knowledge, the majority of members of the doc department are writers. Typically, each writer researches, designs and writes one or more deliverables (and is effectively the project manager for the deliverable). There may be an editor, or the group may rely on peer reviews. There is a manager/team lead, but often the management style is quite flat, with writers making a lot of the decisions on things like style guidelines, user research, and priorities. In a high-functioning team writers are active in the development teams they work with, adding to terminology decisions and usability, as well as editing resource strings. The doc department may have a small tools team, or a writer may do double duty on tools maintenance.

By contrast, a DITA implementation is supposed to be more like building a house: writers create the bricks, but other specialists design the house and build it. Writers create small, structured, reusable modules of content. Architects create templates for the modules, and possibly also oversee information mapping of the modules. Map editors create maps that use the modules to produce deliverables. Editors enforce consistency. A team of tools developers maintains the complicated software required by the process. Team leads or architects act as project managers.

Writers must accept that they must spend a higher percentage of their time on tools and bureaucracy than they did in the traditional doc setup. They must also accept that they have much less control over the final output. This fundamental change often results in writers being unhappy about working in DITA, and the DITA literature goes on about how writers must be assimilated, how failures to return on investment are usually caused by writers having bad attitudes. But stop a moment: When your employees balk at a change, shouldn't you respect their instincts? Unless part of your business model for a DITA transition is that you want to reduce quality for readers, you should at least listen to the people who are responsible for creating that quality.

Instead, DITA proponents say that writers must shape up or change careers. I have heard it put as baldly as that: DITA is sweeping the tech writing field and writers can no longer see themselves as project managers for readers. They are now simply a cog in a wheel. If they don't like it they won't get hired: they'll have to find a new line of work. The real tragedy of this attitude is that the writers who balk at losing their responsibility are the high quality, senior ones who are passionate about their readers and have a professional attitude about how they work. Crappy writers will be perfectly happy assimilating to less responsibility. (They might be less happy when they realize that the transition to structured writing means that it will be much easier to ship jobs off-shore.)

DITA is a beautiful solution... if you're trying to document the parts for an airplane. It would also be suitable if you're documenting 50 similar products, each with end user docs that overlap. My problem with DITA is that it has been sold as a general purpose doc solution. DITA advocates went too far in extolling the virtues of DITA, such as saying that any company that translates content should adopt it.

When people complain about DITA, DITA proponents like to say that it's just a tool: if you don't like the meal, don't blame the knife. But DITA is much more than a tool. It's a tool developed to be used in a particular way, and there's no sense adopting it unless you also adopt the system of structured writing it was created for. The literature about DITA has also created a culture - such as the emphasis on assimilating writers - that permeates many organizations that adopt DITA. And the way DITA is meant to be used, creating reusable modules of content, creates a tendency for doc deliverables to have a certain look and feel. (More on that in another post.)

In fact, DITA is having a profound effect on all aspects of technical writing: on the way we work, the productivity of doc departments, our job responsibilities, and the quality of our output. I know that some call what I'm doing "DITA bashing", but we are past due for a deep reflection on the pro's, cons, and appropriate use cases for DITA.

DITA ROI: Are translation savings all they seem?

This post is part of a series of posts that question some of the claims made about the benefits of DITA adoption. This post focuses on savings in translation costs.

Articles about DITA ROI make some rather sweeping claims about the money you can save by adopting DITA. One prominent DITA proponent writes, "If you have localization in your workflow, you can probably justify the cost of DITA implementation." I would argue that that claim is false: that most companies that localize their content would never recoup the costs of a full DITA/CMS implementation, and that DITA makes sense mostly in fairly extreme cases such as hardware documentation where there are hundreds of similar versions to be documented.

There are two main claims for translation savings with DITA: topic reuse and post-translation DTP costs.

Topic reuse
First, DITA is supposed to save you money because you can reuse topics. "Write once, use frequently" means that a topic is only translated once. Big savings, right?

Maybe yes, maybe no. Translators use Translation Memory. TM is very sophisticated: each sentence is read into memory, and each sentence is flagged if it is an identical or fuzzy match to a sentence before it. If you repeat a sentence, TM will ensure that it is only translated once.

There is still a cost for processing a 100% match, but it is minimal. Typically, the cost for identical repetitions is 15% to 30% of the cost of new translation.

What this all means is that if currently 10% of your topics are duplicates of other topics, your translation costs are higher by 1.5-3% than if you reused topics.

Note: You can get some additional savings from DITA with a CMS by transforming your ditamaps into an interchange format called XLIFF before sending them to the translator. This is a pretty complicated procedure; have a look a this link to see if your organization can handle it. (And I remian somewhat confused about XLIFF: my friend who runs a large translation company says, "Since our CAT tool can handle XML directly, it’s not necessary to go through the migration process into .xliff format.")

Keep in mind that the savings from topic reuse only apply to topics that you are currently maintaining in duplicate places. If you decide to start reusing other topics in more places, that could arguably improve your quality, but it does not improve your ROI. (Plus, I argued in another post that the reuse following DITA adoption is often actually harmful to reader usability: link)

It is true that translation costs rise for reused text when it gets out of sync - when different locations are updated differently. It is always a good idea before sending things for translation to spend some time preparing the files; syncing duplicate content should be part of that check, when it occurs. But even when translators get different versions of dupes, they charge less for fuzzy matches, so the price is not the same as translating the section twice.

My point here is about ROI, not how to write. I am not arguing that cutting and pasting content is good practice. But for many writing teams there is not so much duplication that there's any problem keeping up with it, and if there is, then there are many other systems that provide excellent mechanisms for reusing topics, including Docbook XML, other forms of XML, and Madcap Flare. An extremely expensive full-blown DITA implementation with a CMS is not the only way to reuse topics - and for many organizations, it is not the best. (More on that in a later post.)

Post-translation DTP costs
DITA is supposed to save you money because in other systems, work has to be done after translation. One prominent DITA proponent claims, "Typically, 30–50 percent of total localization cost in a traditional workflow is for desktop publishing. That is, after the files are translated from English into the target language, there is work to be done to accommodate text expansion and pagination changes."

This is a valid point, except that it doesn't state its assumption that you are using bad practices. When you start to localize your DTP content you should remove manual formatting and rely on styles instead. In addition, you can't use formatting that will cause problems in languages that have longer words or are more verbose. This means: stop adding manual page breaks, stop using format overrides (FrameMaker 10 provides an easy way to find and remove overrides), stop putting section headers in the margin, stop setting manual cell heights in tables, stop using forced line breaks (Shift-Enter).

These practices will hugely reduce the post-translation DTP costs (certainly to way less than the stated 30-50%, although there is still a per-page DTP fee). When we talk about the advantages of DITA, we assume people are using good practices; we shouldn't assume that the alternatives are created with bad practices.

Conclusion
Articles about DITA ROI often give you rules of thumb to use in your calculations. Their claims are almost always based on an unstated assumption that your current authoring environment is the most inefficient one possible, and even then their claims can be over the top. It is prudent to ignore this advice and instead go to your translation vendor to find out what your cost savings might be. I have become friendly with the managing director of a translation vendor I once worked with, and he assures me that translation cost is virtually the same when the source is DITA, Docbook, other forms of XML, Flare's XHTML, HTML, etc.

I have spoken with doc teams who are planning to move from Docbook XML to DITA simply because they are confused by these DITA ROI articles and think that the massive translation savings will apply to them. This is not a trivial issue. DITA proponents should be much more precise in the claims they make about DITA cost savings, and doc departments should be much better educated before jumping on the DITA bandwagon.

Note: I'm uneasy about quoting individuals. It isn't fair to single out any particular DITA proponents on how they justify DITA ROI, as many DITA proponents are saying similar things. In addition, I don't mean to impugn the motivations of anyone.

Update: I have a growing unease about quoting people and then knocking down what they say. I have now removed links to DITA proponents I quote. In later posts, I may even stop quoting.

The True Costs of DITA Adoption

For anyone who disagrees with this post: please leave a comment or send me an email. If I am incorrect about something, I will modify the post so that I am not spreading misinformation. And I would love to have a dialog on the topic.

There are many articles that advise doc managers about how to calculate return on investment for potential DITA adoption. Most of these articles seem to be written by consultants who make money by helping companies set up DITA systems: they have a vested interest in making DITA look beneficial. Also, they tend to help out during the initial migration and might not be around when some of the costs kick in: they simply might not be aware. Finally, they might deal mostly with large companies where large expenditures do not seem excessive. For whatever reasons, the literature seems to be underestimating the true cost of moving to DITA.

There can be a lot of costs related to DITA adoption. Here are some that might affect you. (Different implementations will vary somewhat.)

Most of us know about the cost of a CMS, which can set you back over $250,000 (or might be a lot less). You can do without the CMS, but DITA is designed for use with a CMS and you need one to get the full benefits. But the CMS is just the start.

In the early stages of your migration to DITA, you will likely need to hire DITA specialists (the consultants I mention above) to help you plan and set up your system.

You'll likely need more inhouse tools developers, and you may need developers with different skills than you currently have. This is not just to set up the new publishing system and so on, but also to troubleshoot publishing problems, adapt to new browser versions, and address all the bugs and glitches. In my experience there are all sorts of problems that crop up with the relational database (CMS), and also with the ditamaps, formatting of outputs, and many other things. Part of the problem is that the DITA Open Toolkit is notoriously difficult (and could require extra expense for things like a rendering engine). Some of the tools designed to work with DITA are arguably not quite up to speed yet. Your tools developers will also spend a lot more time helping writers.

(If you don't move to a CMS, but use something like FrameMaker and WebWorks ePublisher, you may find that you have a lot more headaches in producing docs without much in the way of DITA benefits.)

You need extremely skilled information architects to create a reuse strategy, engage in typing exercises, and design and edit your ditamaps. This isn't a skill set that people currently in your organization can easily acquire. Even most information architects have trouble adequately mapping topics. For a discussion of the sorts of challenges they'll face, see this series of posts; the moral is: if you don't have skilled architects working on your system, you may end up with Frankenbooks that are not particularly useful for your readers. I raise some additional topic reuse problems in an earlier post: link.

You'll need to spend significant time developing new processes, policies, and internal instruction manuals.

Your team will have to undergo intensive training. In coming years, new writers you hire will also need training. I have found that writers can move to Docbook XML with very little training, but DITA requires a great deal of training, not just for the CMS, but also to learn how to use ditamaps, reltables, and so on.

The migration of content will likely be quite time consuming, with manual work required to correct tagging that doesn't convert automatically, mapping, and a complete indepth edit.

Your writers will need to spend more time on non-writing activities. This can greatly reduce their productivity. Working with a relational database, especially an opaque one like a CMS, is much more time consuming than checking files out of a version control system. Creating reltables is a lot more work than adding links. Coordinating topics is a lot more work than designing and writing a standalone deliverable. Plus, there is a lot more bureaucracy associated with DITA workflows.

With most DITA implementations, topics exist in a workflow that only starts with the writer. You'll probably need more editors and more software.

You'll also probably need more supervisors. The DITA literature emphasizes the importance of assimilating writers to the new regime and then monitoring their attitudes. Pre-DITA, writers were project managers for their own content; with DITA they have to learn to hand that responsibility off to others.

There are some organizations, such as ones that have to cope with hundreds of versions of a hardware product, that have a clear ROI for DITA. But many (most?) organizations could find that DITA doesn't so much save money as redistribute money. Where before you spent the lion's share of your doc budget on salaries for writers, now writer salaries will be a much smaller proportion of your budget. In many cases, companies could find themselves facing higher costs than pre-adoption: they will never see return on their investment. And given the complexities of using DITA, ongoing hassles and escalating costs, some companies are going to find themselves having to ditch DITA and go through an expensive migration to another system.