I'd Rather Be Writing - Tom Johnson

Minimizing Documentation

Tom — 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

21% of Intermountain Chapter Members Planning to Renew STC Membership

Tom — Mon, 09 Nov 2009 15:30:39 +0000

I’m wary of posting on this topic because I don’t want to launch into a long STC discussion. But according to our recent chapter poll, only 21% of our members are planning to renew their STC membership.

21 percent renewal rate

Forty six people participated in the poll (we have 77 chapter members). You can read their list of reasons for not renewing in the full survey report.

I’m wondering — if our chapter is a microcosm for the whole, at what point will the STC have to dissolve or restructure itself? And if it does, what will the restructuring look like?

Blog Sponsors

Design Reviews and Posting Without Answers

Tom — Mon, 09 Nov 2009 01:07:22 +0000

Recently our technical writing team at work (Information Strategies and Design) started holding regular design reviews. The review sessions are patterned after meetings that our interaction designers hold regularly, in which they get together and critique each others designs and approaches toward user interfaces.

In our design review sessions, a couple of members from our eight-person team share what they’re working on and ask questions about challenges they’re facing. We provide feedback and critique their project.

These design review sessions are one of the coolest things we’ve done as a team. We don’t have a strict team style guide or set of standard deliverables. (We do follow the Microsoft Style Guide and, at times, a thin organizational style guide.) But as far as branding the help material, there can be a lot of variation among the online help files, quick reference guides, landing pages, context-sensitive help, interface text, e-learning, video tutorials, or other help materials we create.

If you’ve ever participated in a creative writing group, the design review works similarly. Team members use common sense and experience to guide their questions and reviews. Somewhat in contrast to a creative writing group, though, you don’t have to bring a finished piece to share.

For example, the other week I was coordinating who would share materials for our design review, and one of our team members told me he wasn’t ready to show it. What? I said. The design review is not about showing finished material. It’s better, in fact, to show what you’re currently working on, while it’s still early in the process, before you’ve cemented everything. Oh, he said. In that case, yes.

Parallels with Blogging

I find that the same mindset works with blogging as well. Often times we think we can’t publish a post until we’ve finished a cool thought, or until we’ve finalized a solution to something. But this past week, I added a couple of posts in which I wasn’t quite sure what I thought. In my Theme Parks and External and Internal Input post, I was only part way into a thought. Commenters added to the discussion and helped me better see insights and perspectives on the issue.

I also wrote a post on working with wikis, A Few Surprises in Using a Wiki for Documentation. I’m not an expert on wikis, especially Mediawiki, and there are many things about wiki authoring that I need to learn. But this didn’t stop me from posting about it. Instead, I shared some of the challenges and issues I was facing. And some of the commenters added information that proved incredibly helpful. For example, see this informative comment by Amalia.

Had I waited until I finished in putting together an entire strategy and methodology for authoring on Mediawiki before posting about it, I would have missed out on the guidance and direction early on. It’s from the helpful information early in the process, particularly with challenges I’m facing, that comments on a blog become the most useful. A blog is, remember, a journal, so it contains thoughts and ideas and experiments in progress — not always finished solutions, completed ideas, or tried-and-true methodologies.

What’s true in design review is just as true in blogging. Sharing the current challenges you’re facing will make your experience in the blogosphere or design review process more helpful and rewarding.

Blog Sponsors

How Microsoft Visual Studio Is Doing Help

Tom — Sat, 07 Nov 2009 13:08:52 +0000

The following 10 minute video shows what’s new in the help system for the upcoming release of Visual Studio 2010 Beta 2.

The key trends are as follows:

Help is embedded in a browser because the browser is the predominant mode people use to find information.
Search is the main method for navigating content. There’s no more table of contents or even index.
When you choose a topic, you see contextual topics related to the topic you’re viewing.
You can choose to include online content into the search.
The help is “decoupled” from the Visual Studio application, so the help authors can update the help without waiting for the next release of Visual Studio. (This is what I referred to in my content independence post.)

The direction the Visual Studio Help team is moving reflects my own trends as well: moving towards a web-like experience with help, relying more on search, adding contextual topics based on what the user is viewing, and publishing help in a location I can update on the fly.

(Thanks to Keith Soltys for the link.)

Blog Sponsors

Podcast Roundtable for PodcampSLC Series

Tom — Fri, 06 Nov 2009 21:05:01 +0000

I recently had the opportunity to participate in a podcast roundtable as part of a series to promote the upcoming Podcamp Salt Lake City, planned for March 26, 2010. Podcamp is a conference on podcasting and videocasting, with local presenters giving both beginning and advanced sessions in an informal setting.

Guests on this round table show include Gregory Lemon, Drew Tyler, Thom Allen, and me. We recorded it at the Salt Lake Beta Loft, which is a space for freelance professionals to work and collaborate. Drew, who runs the Beta Loft, is a video genius and put together the video.

Blog Sponsors

Theme Parks and External and Internal Input

Tom — Fri, 06 Nov 2009 05:41:05 +0000

This week I’ve been on vacation in Florida, visiting my family and touring the theme parks — Seaworld, Disneyworld, and (soon) Busch Gardens. I used to live in Florida and would go to Busch Gardens all the time. But this week is more extreme. Our first day at Seaworld, I realized my theme park endurance was poor. The next day at Disney was much better, even with just 6 hours of sleep the night before. The second time around Seaworld (of course one day wasn’t enough) was like stopping off for a brief jaunt at the mall, except when we temporarily lost our daughter, which sent us on a roller coaster of emotions.

While walking around theme parks, I’ve been thinking about a talk Nicole Mazzarella, author of This Heavy Silence, gave last month at the BYU-I writing conference. Talking to a group of would-be writers, Nicole explained the need to “live in the moment.” She talked about the need to disconnect from whatever media is taking you away from the moment you’re in — Twitter, Facebook, email, IM — and to focus on the moment you’re in. This ability to be in the moment is as critical to writing as other time-worn advice, such as reading or reflecting.

I wasn’t quite sure what to do with that advice. But now I’m starting to understand.

Theme parks floor you with mesmerizing shows, constant music, visual stimuli, greasy food, stomach-losing rides, character-filled stories, and an overall constant stream of external input. The more external input that comes in, the less internal input you need to generate. When I’m flooded with external input, I seem to lose touch with my own thoughts and direction. In this way, theme parks are like TV, a continual escape where no internal input of my own is needed. I just follow the map, hold onto my kids, and move from show to ride to food kiosk to exhibit to show to ride until the day finishes, and then I drive home and collapse from exhaustion.

When I’m not at a theme park, when I’m living my regular life, immersed in the moments of silence so typical of writing and a quiet family life, I often feel a tendency to turn on sports, the radio, Google Talk for email or IM, Twitter, and start any other form of external input I can find.

But that external input takes me away from the moment. It disrupts my attention on what I should be doing or thinking about. Perhaps there’s more to the moment that I’m missing when I fail to focus. This isn’t a single task versus multi-task discussion, or an argument about how each disruption requires 20 minutes of downtime to refocus. I’m saying that when I put myself in situations of extreme external input, like a theme park, the amount of internally generated input is minimized. With minimal internal input, my creativity sinks, and my muse goes mute.

But this is a balancing act, because external input is often the stimuli that generates internal reflection and analysis. I’m still putting together my thoughts on internal and external input. For now, I’m starting to be acutely aware of the difference. Can you help clarify what I’m trying to say?

Blog Sponsors

Podcast on the Seven Deadly Sins of Blogging

Tom — Thu, 05 Nov 2009 16:59:00 +0000

Download MP3
Length: 1 hour 45 min.

Over the last month, you’ve been seeing various posts on my site about the seven deadly sins of blogging (being fake, irrelevant, boring, unreadable, irresponsible, unfindable,, and inattentive). I mentioned at the beginning of my seven deadly sins series that I was preparing for some upcoming presentations on blogging. I first presented on the Seven Deadly Sins of Blogging at WebWorks Roundup 2009. I gave a similar presentation to the STC-Suncoast chapter (in Tampa, Florida) last night. The latter one I recorded.

While the content of both presentations was supposed to be the same, that’s not how it worked out. The presentation to Suncoast kind of veers off in different directions half way through. I also decided to bookend this podcast with a few thoughts before and after the presentation while driving (hence the length).

Blog Sponsors

The Long Tail of Online Profitability

Tom — Wed, 04 Nov 2009 05:27:11 +0000

Last week I listened to David Peralty give feedback to Jeff Chandler about his WordPress Weekly and WPTavern.com projects (see episode 75). David praised the community and visibility that Jeff had created through his weekly podcast and forum, in addition to his WPTavern.com site, but noted that he was aware Jeff hadn’t reached the monetization goals he hoped to achieve.

In other words, Jeff has done a tremendous job at creating a community and audience for his site and podcast, but he hasn’t found a way to make real money off his activities. If you monetize your online activities, you can then justify and devote more time to the activities to establish and grow your community.

But if you can’t make any money, it’s hard to justify spending so much time online. And if you can’t spend the necessary time online to build your community, your site or podcast won’t take off.

Although David was critiquing Jeff, I felt like he could have been equally speaking to me. I listened carefully, waiting for the key ingredient Jeff was missing. What was he not doing? What was he not seeing? How does one move from a hobby site/podcast that has a growing enthusiasm to one that makes enough money to sustain you full time?

I have a few notes, gathered from anecdotes and people I know:

Just recently Cameron Moll, a well-known web designer whose blog is Authentic Boredom, quit his job and turned to freelance full-time. He sells posters and job listings on his site and does some freelance work, I believe.
A basketball buddy of mine explained that, according to Jason Van Orden (who creates the Internet Business Mastery podcast), I should be making $1 per month for every follower I have with my site. Translating that, I should be pulling in more than $2,000 + every month.
My former brother-in-law taught me that information products about making money online are more profitable than selling regular products. He’s an eBay mogul who earns thousands of dollars teaching people how to drop-ship products on eBay. The business of teaching others how to drop-ship is more profitable than actually drop-shipping.
About a year ago Jane kept prodding me to sell some ads in my sidebar. I finally did, mostly by contacting companies separately and pitching ads, and it worked. But ad revenue doesn’t scale. I only have about 12 spaces there. (By the way, there’s an empty spot, if you’re interested.)

Lately I have been mostly resigned to the idea that “information wants to be free,” and that the real benefit of having a blog or podcast is the capitalization on the attention economy of my audience, as cool and unprofitable as it sounds.

But the other day I was talking with Sean, my brother-in-law (a different one), who is an interactive programmer and runs his own company, HD Interactive. Sean manages a successful online business, so I asked him what I am missing. What is that missing element that I could adjust so that I would be profitable? Create a premium version of the podcast? An online site with video tutorials for WordPress or other software? Sponsored posts? WordPress blog design projects? T-shirts? Webinars? e-books? A forum?

As I talked with Sean, it became clear to me that no single product would provide an online revenue model of the sort I’m searching for. There is no missing ingredient. Rather, the revenue model of the Internet is the Long Tail. Of course! I should have seen it coming.

If you’re unfamiliar with the Long Tail, it’s a model by Wired Magazine’s Chris Anderson and purports that online stores such as Amazon.com make more from long-term sales of their niche products than they do by selling mainstream products. For example, the Grateful Dead Mug from 1979 that someone purchases from your online store for $5 combines with a thousand other low-selling, inexpensive niche products to surpass the income that you make from selling top-of-the-chart music CDs or other mainstream products.

The neat thing about the Long Tail is that it seems to apply to so many phenomenon online, not just revenue. There’s a long tail of participation. A long tail of travel. There’s even a Long Tail blog, where all of this is discussed. I never thought the Long Tail could apply to my attempts to make money online.

But as I spoke with Sean, I realized that the revenue stream for online activities really is the Long Tail. You won’t make your fortune selling one product or service (even though some have). Instead, it’s the combination of various revenue streams, of selling a variety of products, that combines to create an income to equal your goals.

For example, you sell a premium and paid version of a podcast, and maybe 50 people sign up for the premium version. You sell ads in your sidebar, and maybe a dozen sign up. You create a forum and offer a tiered membership, and some more sign up. You sell T-shirts, mugs, and other paraphernalia, and some more sign up. You sell video tutorials and e-books and print books, and more sign up. You present at conferences and coordinate webinars, and more sign up. You offer one-on-one tutorials and online training, and more sign up. Any of these methods alone would produce income that is weak and unsustainable, but the combination of them all accrues a revenue stream that is substantial.

Now that I think about it, this is also the strategy Jason Van Orden recommends in a podcast with a hobby geneologist (though I didn’t realize it at the time).

The Long Tail may be the model underlying a number of phenomenon on the Internet. It may also be the best answer to the conundrum of making money online from a popular blog or podcast.

Blog Sponsors

Wikis and the Holy Grail of Content Independence

Tom — Tue, 03 Nov 2009 03:12:38 +0000

If you work in a large corporate environment, you’re familiar with restrictions about accessing production servers to make updates or additions to your help content. To touch anything on a production server, you have to go through the change release process, which requires a lot of paperwork and procedural hassle. Almost no project manager sees documentation as important enough to release a new version of the software into production on account of a need to update the help.

And yet, I regularly need to update the help after the application is released. For example, in the previous project I was writing about, the Local Unit Calendar, after release I learned about a bug in production. I received a couple of questions from a user, and the answers weren’t in the help. I had an error in the section about changing calendar color. And I needed to add some more instruction in another section.

When I explain to system engineers that I need a server for my help that I can update on the fly, they always ask why. Why can’t I just include my help content in the application? However I explain it, the reasoning always comes off sounding like an excuse for not being able to finish my work on time for release.

And yet, I sometimes don’t find out about an application until two weeks before the application goes live and needs documentation. Although I need to create video tutorials, the interface isn’t frozen until the application goes into hardening and becomes a potential release candidate.

If the materials need to be translated, the Translation department requires at least a month of turnaround time. If the content will be printed and sent out to users, I may have to get the content approved from a department that ensures message consistency.

If subject matter experts don’t take time to carefully review the material and video scripts before release, there’s a good chance the help will contain some inaccuracies. Project managers and quality assurance engineers rarely have time to review help material the week before a release. If I don’t submit the help content to peers for a style review, there’s a possibility that typos or inappropriate formatting will also sneak through.

In short, there’s a host of reasons why the documentation might need to be updated after the application is released. If I could access the help content and continue to add and adjust it at any time, independent of application releases, it makes documentation less of a time crunch the night before (for example, to finish the video tutorials for the calendar app., I stayed up until 5 a.m. the night before).

The concept of having control over your help content, to update it at any time, is what I’m calling content independence. Establishing content independence in your publishing environment may be a battle that can take years. For example, at a previous job, it took five years to finally convince architecture that we needed and deserved our own independent folder on a production server.

In my current situation, I’ve pursued publishing routes in infrastructure that would enable on-the-fly updating, but for two years in a row I’ve come up empty-handed. With wikis, I think I’ve finally found the holy grail of content independence.

By nature, wikis sidestep the problem of file transfers, because you can always immediately access and update the content through the browser interface. For content outside the interface, such as PDFs, SWF files, or diagrams, which you can’t code into wiki syntax, you can still upload the video tutorials through Mediawiki’s file upload utility (and probably through a lot of other wiki interfaces as well).

Mediawiki's file upload utility

The interface file upload utility gives you a tunnel to production without having to go through change release!

Note: You can’t upload every type of file through Mediawiki. HTML files and Javascript files, for example, are usually forbidden file types. Also, the file upload is one at a time, so a traditional webhelp system generated by Flare or RoboHelp wouldn’t be uploadable through a wiki’s file upload utility. But if you’re using a wiki for documentation rather than a static help authoring tool, this isn’t an issue anyway.

To enable file uploads in Mediawiki, you have to make a few tweaks to your localsettings.php file. You may have to adjust your settings in the php.ini file too. And if you want to embed your videos, you may want to install a Flash extension. I’ll include instructions for doing all this in another post. But basically, despite the drawbacks that wikis involve, they provide you with an invaluable advantage in help authoring: content independence.

Blog Sponsors

Reinventing Yourself Through Your Blog

Tom — Mon, 02 Nov 2009 04:10:21 +0000

The other week, while I was at the WebWorks Roundup conference in Texas, where I was one of the featured industry speakers, I was sitting next to Anne Gentle during one of the panel sessions, and I asked her about branding. It seems like once you become branded through your blog, it’s hard to reinvent yourself.

I was speaking at WebWorks on blogging and web 2.0. More than anything else, my blog has branded me as a blogger. This brand has led to numerous speaking invitations at conferences and chapters. The more I speak about blogging, the more I become branded as a blogging expert –- it’s a cycle of branding that perpetuates itself.

At the conference, I learned that although some people have branded themselves online in certain ways, they can be much different in person. For example, online you know Richard Hamilton, founder of XML Press, as an entrepreneurial publisher focusing on the technical communication market. You may also see Richard as an experienced manager through his recent book Managing Writers. And you may gather that Richard is a careful, analytical thinker from his lengthy conference write-up posts. That’s how Richard has branded himself — as a publisher and manager.

But Richard has another side to him as well. He’s a pilot and previously owned his own airplane. He loves reading literature, especially mysteries. For example, he has read Sue Grafton’s mystery series (A is for Alibi, B is for …) series up to G. His whole face lights up when he starts talking about mystery novels with another mystery aficionado.

He boots his computer in Ubuntu and prefers to write everything in DocBook XML. He also seems to enjoy long car drives (for example, he drove from Colorado to Texas and back for the conference). More than anything, Richard is one of the most warm, friendly, and conversational people you will ever meet.

Alan Porter is even more of an interesting figure when it comes to branding. Online you know Alan as the head of WebWorks (or VP of Operations). You read his blog as an expert in the tech comm industry, especially with wikis. His forthcoming book, Wikis: Grown Your Own for Fun and Profit, will only solidify his wiki branding. He also blogs about trends in user behavior, from observing, for example, the way his teenage daughter approaches her homework.

But in person, you’ll find that, like Richard, Alan has another side to him entirely. A cowboy-boot wearing Englishman, Alan is an avid comic artist. Mention conferences like Comicon and Dragicon and his ears perk up. He regularly writes the stories, dialog, and scripts for the comic book CARS.

In addition to his drawing talents, Alan has also written books on James Bond, Batman, Star Trek, and the Beatles. He has strong feelings about the importance of storytelling. In fact, Alan works only 30 hours a week so he can focus on his writing.

Alan has written a mystery novel set with NASCAR racing and another novel about Shakespeare pretending to be Christopher Marlowe, which an agent of his was shopping around Hollywood for a possible movie. Alan is also a consultant for Tedopres, a company focused on simplified technical English. He can fly out to your location and train your employees on simplified technical English techniques.

Alan understands the importance of recording presentations. He records all major WebWorks conference sessions, making them available at first on a limited basis and then eventually opens them up to everyone. He’s allergic to gluten, is married to a court reporter, and when you mention his competitor’s products, such as Flare, he breathes a deep sigh.

I’ve gotta say, Alan is one of the most interesting people to meet, because unless you know this other side of Alan, all of this comes as a complete surprise. It’s a surprise mostly because Alan has chosen not to brand himself this way online. In fact, he has a policy that he will not write about either his company’s products or his competitor’s products on his blog.

Blogs provide you with an opportunity to brand yourself with an identity you want to be known by. But you have to be careful what you blog about, because that brand then stays with you. You become known for that brand, and it can be hard to change.

Reinventing yourself with a new identity isn’t impossible. It just requires you to shift your focus, to start writing about a new topic.

I mentioned at the beginning that I’m not so eager to be branded as a blogger (and podcaster and WordPress person). Ideally, I would like to be a screencaster and wiki expert as well. To make that happen, I’ll have to shift the focus of my blog — for about the next 200 posts.

I could make the shift, but I think I prefer to let things happen in a more natural way. It’s more interesting to let water flow in the direction it wants to. And then every once in a while look up to see where you are.