I'd Rather Be Writing » Favorites

Why Help Authoring Tools Will Fade

Tom Johnson — Wed, 25 Nov 2009 11:30:26 +0000

I read a blog post the other day that I can’t stop thinking about. In the Myth of Single Sourcing, Michael Hiatt writes,

The main issue for me is between authoring static in-house documents using single-sourcing methods before publishing, or capturing information sources dynamically after publishing from online social networks, linked data sources, and knowledge mashups.

The myth of single-source authoring is that it actually has a life in the future and remains a viable goal for many information developers. With so many mega-trends against it—such as the belief that static authoring from a single vantage point from a single author paid by a single organization is a workable system—seems ludicrous. Instead, we should be looking to capture, sequence, and give context to the wealth of rich content already published in context from the Web. Collaborating with the many subject experts, authors, videographers, bloggers, tweeters, and writers coming together on the Web with shared interests will be powerful if it can be harnessed.

The myth of single sourcing

Michael undercuts the idea that you can create help from a single author working from a single perspective in a single point in the organization. To add to this scenario, usually that author is an outsider to both the environment and business processes he or she is documenting. Further, the author usually moves on to another project as soon as the software is released.

This morning I had a meeting downtown at SLC headquarters. I’ve become accustomed to wearing business casual clothes to work, but at headquarters, I have to wear a full suit because that’s the dress code. In an early morning meeting, I listened to several department leads explain my new project. It would involve extensive knowledge of cataloging and archiving techniques, a robust off-the-shelf system that had been customized, five main divisions or modules to conquer, each with their own resource leads, about 200 constantly rotating users complementing a core group of specialists, and an aggressive time frame.

As I listened and glanced through the archiving and cataloging procedures (did you know there’s a Society of American Archivists, and that they have in-depth protocols for how things should be done?), I realized that learning the business process surrounding the application would require complete immersion in each of the five divisions over the course of several months. I would need to constantly interview subject matter experts, participate in the actual archiving and cataloging processes, and make sure everything I created was reviewed, checked, and edited for accuracy by each of the five major subject matter experts. The end documentation would probably be several hundred pages for the initial release.

Keep in mind that I have about three other concurrent projects that I’m working on with approaching deadlines (unlike developers, no writer ever gets to work on just one project). Could I pull something together by February/March?

At this point, Michael’s post was resonating like a blinking banner in my head. Authoring from a single vantage point from a single author is … ludicrous.

Even if I were to import existing documents and materials from SMEs into a HAT, who would own it after I finished? Would I become a permanent installation in the department, constantly processing updates, verifying instructional clarity, addressing gaps and making edits? If not, would the documentation become stale six months after release, when SMEs decided to change their business processes?

In an organization where several thousand people have only a handful of actual technical writers, we’re a scarce resource. I bounce from project to project, like a little visiting angel (or devil) who works a little documentation magic and then moves on.

Another group on my team is tackling an even larger project, one that involves complex financials. They’re using Flare. They started using X-Edit and entitled a handful of business writers to contribute content with it, but X-Edit proved either too buggy or unworkable. Now the business SMEs are passing Word documents to the guys with Flare, who are inputting the information into the HAT. After release, the idea is to have the business department own the documentation and continue making updates using Flare. It will be interesting to see if they actually do it.

In thinking about these robust software scenarios, where products require extensive knowledge of business processes, have elaborate interfaces with hundreds of possible tasks, and are run by dozens of specialists constantly refining their own business processes, is there any other platform besides a wiki that can actually work? What else can you use to enable 10 different authors to make simultaneous updates, to maintain the documentation after the release? How else can you infuse the documentation with the intricacies of a department’s business processes?

Using any of the standard authoring tools — Flare, RoboHelp, Author-It, Doc-to-Help — leaves you with the ridiculous model of a single author working from a single vantage point from a single organization trying to pull together an ocean of information. Because that model is untenable and unscalable, HATs will fade in favor of collaborative web-based authoring technologies.

Note: Stay tuned for more on this topic. I’m interviewing Michael for a podcast this weekend. It turns out he practically lives in my backyard.

WordPress note for Thanksgiving: Remember that I do WordPress consulting, including design, development, and implementation of WordPress sites. Thanksgiving is a perfect weekend to get your blog online. If you need my help, contact me. Even if it’s only a small site tweak, such as changing font sizes or integrating Share This buttons, I can help you out.

Blog Sponsors

Minimizing Documentation

Tom Johnson — Wed, 11 Nov 2009 07:32:54 +0000

I recently attended an STC chapter presentation on interface design, and the speaker, Grant Skousen, showed us the following graphic.

Simplicity and complexity

We then launched into a discussion about minimalism. I think we all agree that minimalism in user interfaces is an increasing trend, especially with the success of the iPod and iPhone, which are all about simplicity and minimal design.

Grant said every time you add something to an interface, you should take something away. Keeping the interface simple ensures you aren’t crowding out screen real estate. He then quoted Elder M. Russell Ballard, who said:

To innovate does not necessarily mean to expand; very often it means to simplify.

If you just keep adding components to the interface, your core features get diluted, Grant said.

I asked Grant if the same principles of minimalism in interface design also applied to help materials. No doubt you’ve heard some say that you don’t have to document everything.

Grant wasn’t sure if it applied. Minimalism in documentation does have a similar effect as minimalism in design, though. Cutting out the extraneous text, unnecessary diagrams, and edge-case videos reduces content dilution. Your users can focus on the key help material that matters and that you want to be sure they read.

Is less always more? I’m not sure. But if Apple’s minimalistic designs are any indicator of trends, minimalism in documentation is something to pay attention to. Here are five ideas for minimizing documentation:

1. Make the interface simpler.

If you can fix a confusing interface design or workflow, you can reduce the need for excessive instructions. This is the ideal solution to minimizing documentation, but it requires you to get involved in the development process early on, when you’re at the prototype stage. At times you have to present your case like a lawyer, bringing the evidence of user feedback and metrics to persuade project managers and designers to change the prototypes.

2. Make the help context-sensitive.

If you can present the user with help specific to the page or task at hand, this reduces the perceived amount of documentation that the user encounters. This may not reduce how much text you write. In fact, it may increase it. But from a user’s point of view. he or she won’t have to browse through long tables of contents or search for the right topic. The help is essentially just one page, right there (hence, minimal).

3. Give users a quick reference guide.

You can give users a short quick reference guide (under five pages). This gets the user up and running with the system. Quick reference guides reduce the instruction for the system to the core tasks and presents those instructions in an abbreviated, concise way. If the user needs more information, point him or her to a full database or online help file where or she can search for answers.

4. Reuse content topics and paragraphs.

If you can reuse the same material for multiple guides, this reduces the amount of documentation you have to write. Especially if you’re writing a manual for several different versions of a product, or role-based guides for different groups of people, or translating your guide into multiple languages, the more you can reuse paragraphs, chunks, and topics, the less documentation you have to manage.

5. Add to the documentation when users request the information.

Don’t fall prey to the mindset that every scenario, problem, and possible use of the application needs documentation. If you set yourself this task, you may be writing hundreds of topics for what is otherwise a relatively simple application. Instead, decouple the help content from the application so you can update it on the fly. Monitor support logs, analyze metrics, and listen to other user feedback. When users ask questions not included in the help, add that topic to the help. This is a living documentation model. The documentation grows to the size it needs to grow, and no larger.

Conclusion

Minimalism in documentation is a growing trend. Recently Chrysler even abandoned their long manuals in favor of shorter guides and DVDs. What are your strategies for minimizing documentation?

Blog Sponsors

Avoiding the Shut Down Mode

Tom Johnson — Sun, 30 Aug 2009 23:50:53 +0000

In a recent episode of This American Life titled “Going Big,” Geoffrey Canada explains his model of Baby College, which is a nine-week workshop where poor, inner-city parents to be learn to raise their children in ways that break their children out of the poverty cycle. Canada gives up on breaking the parents out of the poverty cycle and instead focuses on teaching parents the childhood rearing techniques that will enable the children to break free.

What exactly are these techniques? Nothing that middle-class suburban families don’t already know — read to your children, encourage your children with positive words and praise, give your children opportunities to develop and play, and other norms. In contrast, Canada said some parents in poverty circles feel that a well-behaved child is one who sits quietly and keeps to himself. At every point they seem to “shut a child down” — saying Sit down, Be quiet, Keep your hands to yourself, Get over here, Shut your mouth, and so on.

Listening to Canada describe the behavior, I thought of an experience I had while living in Harlem. I was going to graduate school at Columbia, and due to housing shortages and high costs of living, we lived on 134th and Lexington. One day while walking down the sidewalk, we saw a mother scolding her boy, who was no more than 10. Apparently he had said a swear word or two, and the mother said, “Boy, you better shut your *&^%^& mouth or I’ll whack you,” or something like that.

It struck me as absurd. Didn’t the mother realize where her son had learned to swear? It was the equivalent of a parent smacking a child because the child smacked someone, and telling the child — while smacking him — not to smack anybody. Could it be any more obvious?

This was, as you probably guessed, before we had our own children, and since then we’ve realized that it’s not always so easy to avoid this behavior. But what Canada said — about parenting that “shuts a child down” rather than lifts him up — made me think.

Shutting a child down, he said, prevents the child from developing and exploring and discovering the world, which is how children learn and grow. If you force children to sit quietly on the couch, probably watching TV, never speaking up, keeping to themselves, and never going outside prescribed boundaries, you prevent them from growing through the active development that occurs when children can freely express and explore their environment as themselves.

It’s easier to explain this model than to actually implement it, because last night at the dinner table, while I was relaying this to Jane, our three children were howling like wolves in the living room so loud I could hardly hear myself think. Five minutes later, they were prancing around naked in a ceremonial-like chant prior to their bath. As I tried to restrain myself from “shutting them down” and instead let them reap whatever development they could from hooliganism, we finally both told them to basically pipe down and get in the tub.

Later that night, as I was trying to help the littlest two fall asleep, they snuck out and showed me how they had abundantly decorated their faces with felt-tip markers. I was already frustrated with something I couldn’t figure out on the computer, and since it was the ninth time I had to guide them back to their rooms, I was pretty angry and let them know it. I snatched the pens and washed their faces with soap and water somewhat harshly.

We’re lucky we have girls, because as far as I can tell, boys can be worse in the way they explore and express themselves. My colleague explained how he recently purchased new couches and came home one day to find his boy had taken a knife to each of the cushions, making big holes. Other parents’ boys I know like to put pennies in VCR slots. When they come over to our house, their kids are pushing every little knob and button they can find.

And yet, despite the craziness, destruction, and inappropriate use of seemingly everything, this is how children learn and discover and grow. Lock them up in a dark room, where they can’t see or hear or do anything, or make them sit quietly, where they can’t freely move about and express themselves as self-acting individuals, and you lock them from growth.

I’m not recommending a parenting model that eliminates correction or restrictions on children, because I’m still doing it every day. If my children had their way, they would eat Skittles for dinner, watch Phineas and Ferb until about midnight, and then fall asleep on the floor in their clothes, without brushing their teeth, saying their prayers, or reading any books. So of course there is some balance to this freedom model. But something just feels right about giving children freedom to act independently without always shutting them down, even when they’re out of line.

As I thought more about this parenting model, I also thought about professionals in careers. It seems at some point, you learn in your job that you should sit still, keep to yourself, restrain from experimentation and foolishness, and simply do the tasks that you’ve been given. We lose our sense of discovery and experimentation. People get a little uncomfortable when you do something they didn’t request and which they’re not expecting. When you break free of previous expected norms and try something new, you take risks that aren’t always rewarded.

The activity in which you break free could be anything — decorating your cube, implementing an extremely conversational style in your writing, putting in some elaborate graphics. Maybe you’re a manager who decides to switch places with colleagues for a day, or you’re at team lead who conducts a meeting that consist entirely of role-playing scenarios. If you’re a technical writer, maybe you decide to spend half a day playing ping pong with the developers just to build rapport, or you curiously lop off the first five pages of legal and useless introductory material of your help content because you “just don’t like it.” Maybe you style the table of contents in an experimental way, or start embedding Flash videos in PDFs.

Whatever the activity, if it doesn’t involve some level of play, some movement outside the prescribed box, then haven’t you become the same child sitting quietly on the couch, keeping his mouth shut and his hands to himself because that’s the box your parents — or manager or company — put you in? The overall effect of these experiments and expressions, even when inappropriate or inefficient, is growth and awareness in ways that that worker who has been “shut down” will never know.

Blog Sponsors

If You’re a Writer, Write

Tom Johnson — Mon, 13 Jul 2009 13:03:34 +0000

Many of you—at least a third, I’m guessing—are writers by nature. You majored in English, dabbled in creative writing, probably immerse yourself in literary novels at lunch. You love the written word. You revel in your expertise in grammar, your fine tastes in sentence structure and semantics. You proudly display your Chicago Manual of Style on your bookshelf. Maybe you even secretly want to be a novelist. Perhaps you have an unfinished manuscript tucked away in your desk drawer that you think about finishing. Writing—the more creative, literary kind—is in your blood.

Fortunately, now is one of the best times for writers to be alive, because you can write and publish without hassle. According to Phillup Greenspun, the web provides a flexible format that removes traditional restrictions of length. You’re no limited to magazine length (5 pages) or book length (200 pages) of content. You can publish 20 pages essays, or 2 paragraph thoughts. You can write fiction or nonfiction, on any topic you want. You could publish your novel serially, or write your book chapter by chapter in a wiki-like way, or do any creative thing you want.

So why is it that, given the opportunity and tools to write, so few embrace it? I have several thoughts as to why.

1. You enjoy the idea more than the work

Most people enjoy the idea of being a writer more than the act of writing. The same could be said of a lot of activities. I once fantasized about doing triathlons, but it was really the idea of being a triathlete that appealed to me more than running, biking, and swimming. I also once fantasized about medicine, but it was the idea of “being a doctor” that appealed to me more than putting my hands inside bloody skin and tissue to fix people.

The truth about writing—the reason why people may daydream about “being a writer” but never seem to find the time to write—is that it’s a lot of work. Coming up with original ideas, organizing and structuring those ideas, editing and polishing your sentences, refining your thoughts, and finding time to do it all rather than sit back and watch TV or work in the yard—is something akin to completing that triathlon. It’s a lot of running/thinking, swimming/writing, and biking/editing. And it’s taxing. Winston Churchill compared writing to fighting a monster:

Writing a book is an adventure. To begin with, it is a toy and an amusement; then it becomes a mistress, and then it becomes a master, and then a tyrant. The last phase is that just as you are about to be reconciled to your servitude, you kill the monster, and fling him out to the public.

Instead of slaying the monster, it’s easier to sit back and think about “being a writer.”

2. Your elevated awareness sets higher standards

Another reason you may not find time to write is that your literary awareness is on a higher level, which makes writing more challenging. You’re aware of what good prose looks like, and so the standards you set for yourself are more rigorous. You’ve got William Faulkner and Jane Austen or some other famous writer on your mind, and you know that to write something worth reading, it will take a lot of time, more time than you’re willing to commit. For the limited time you do have, all you can produce is mediocrity, which you won’t sink to.

This high-brow position isn’t very excusable, because knowledge of higher standards often gives you more talent and capability. And if you have limited time, you can just stretch your efforts out over a period of time. Still, being able to recognize that your first drafts are junk can be a motivational deterrent.

3. You’ve fallen out of the habit

Although the previous two reasons are possible, most likely you stopped writing because you’ve fallen out of the habit. Desiderius Eramus, a fifteenth-century Dutch humanist, said, “The desire to write grows with writing.” The reverse is also true. The desire to write shrinks the less you write.

Habits aren’t particularly tricky to establish. It’s mostly a matter of doing it. Once you start doing something, it becomes easier to do it. When asked for advice from a young would-be writer, E.B. White, author of dozens of essays, said:

You asked me about writing—how I did it. There is no trick to it. If you like to write and want to write, you write, no matter where you are or what else you are doing or whether anyone pays any heed. I must have written half a million words (mostly in my journal) before I had anything published, save for a couple of short items in St. Nicholas. If you want to write about feelings, about the end of summer, about growing, write about it. A great deal of writing is not “plotted”—most of my essays have no plot structure, they are a ramble in the woods, or a ramble in the basement of my mind. You ask, “Who cares?” Everybody cares. You say, “It’s been written before.” Everything has been written before.

In other words, if you want to write, just open up a blank Word document and start typing. It’s that simple. The rest—the form, the purpose, the ideas, the publications—will follow. The more you write, the more desire you’ll have to write. And the easier writing will become.

Final Thoughts

I decided to write this post because I’m frequently asked—by fellow writers—why I blog [write] so much. For me, I consider myself foremost a writer. I majored in English, studied creative nonfiction writing, and find value in the act of writing, especially when I have nothing particular on my mind. I enjoy creating something from nothing.

I prefer personal essays and nonfiction over fiction, so the blog is a natural form for me. But whatever preferences for form you have, don’t give up on your more creative or literary writing. You don’t have to submit your writing to journals and magazines for publication. A blog can be a worthy publishing format. I get more reward from the comments, trackbacks, emails, and other feedback on my blog than from any other writing endeavor. Whatever style and format you choose, if you’re a writer, write. The opportunity is there.