I'd Rather Be Writing » single sourcing

Interview with Ugur Akinci about Technical Communication

Tom Johnson — Mon, 23 Jan 2012 22:41:39 +0000

Ugur Akinci

The following is an interview with Ugur Akinci, a technical writer for Honeywell Corporation. Ugur asked me these same questions for an interview on this site. After answering them, I was curious about how he would answer the same questions, so I asked Ugur to respond to the questions for my site as well.

(1) How long you’ve been a technical communicator? Where do you work right now? How would you characterize a typical day at work?

I’ve been a technical communicator for over 13 years, lucky enough to be working for Fortune 100 hi-tech corporations. Currently I work for Honeywell Access Control Systems.

A typical day would mostly consist of writing user, installation, and configuration manuals and drawing illustrations that go with such manuals. Communicating with my colleagues, managers, and SMEs through email, phone and in person and participating in meetings, teleconferences and webinars are also a part of my typical day in office.

(2) How did you become a technical communicator? Did you start out as one or did you switch to it from something else? What was the reason?

I was originally trained as a sociologist but things happened and I never worked in academia.

I started out my career in the late ‘80s as a Desk Top Publishing expert of sorts. When the first Apple Macintosh came out I’ve spent all my savings to buy a Mac SE and a dot-matrix printer and started to design and produce magazines, brochures, flyers, whatnot. I enjoyed that very much. That led to my still continuing interest in page layout and graphic design. In the ‘90s I found myself writing more and designing less, and eventually I became a full-time copy writer.

Between 1994-1998, I worked as a journalist in Washington D.C. for a daily paper, covering the U.S. State Department and the U.S. Congress. Very exciting and busy four years those were but at the end I was forced to look for something else because journalism was not paying much. So like quite a few other tech writers that I know of, I’ve made the switch from journalism to tech writing in 1998 and never looked back since then.

(3) What is the single most important change that you see in the technical communication sector since you first became a technical communicator?

Emergence of structured authoring and single-sourcing; the relentless push to automate and standardize the document production process while dropping the unit costs. I think in the future technical writing will be a lot less about writing and a lot more about coding, mapping, and transcribing.

Also, I think the role of technical illustration will steadily grow in this age of multinational products and services catering to a multicultural customer base, all speaking different languages. Words are not universal but images are. Writers who can also draw have a clear job-market advantage for that reason.

(4) In your judgment, what is the best and worst thing about working as a technical writer?

For me the most satisfying aspect of technical writing is the way it forces me to make sense out of chaos and bring order to not-so-orderly processes. That workflow forces me to face my own deficiencies and motivates me to understand my thought process better while trying to describe the object of the same thought process.

As a secondary note I can also say that this is the best-paying writing job I ever had. If you love writing but you’d like to take care of your family as well, then by all means you should think about becoming a technical writer. I tried journalism, poetry, copy writing, screenplay writing, political commentary, and freelance article writing – but nothing comes close in terms of the material security that technical writing provides.

The worst about technical writing is that it’s by definition not an emotionally expressive genre. It’s not creative in the sense a screenplay or a poem is creative. It’s not designed to move others emotionally but to direct, instruct, and train others. I’m the son of a singer and a painter and was raised at a home full of music and art. I still have a deep interest in artistic expression of all kinds. Thus from time to time I balance the scales by taking a break from technical writing and doing something else, like watching a movie or writing a poem.

(5) What’s your advice for those who are just starting out their careers as technical writers today?

Try to bring to the job as many side skills as you can. Don’t go into the battle with a single handgun on your hip.

For example, if you like to draw and paint, that’s great since technical writers who can also draw illustrations will be in great demand in the future. For employers it’s a clear two-for-one deal.

Same goes for programming and all kinds of engineering skills. If you have a knack for network administration, so much the better since most of the systems that I’ve documented required a good understanding of the way client-server systems are networked together.

If you know HTML, Javascript, PHP, SQL, or a traditional programming language like C++ or Java, those are all the kinds of skills that will propel you to the head of the queue in your job search. Don’t let such skills become dormant thinking they have “nothing to do with writing”. On the contrary — in technical communication those are all big plusses.

Lastly, you should seriously consider specializing in structured authoring in general and DITA as a specific single-sourcing platform. In the future I believe such “technical writers” (I wouldn’t even know if it’d be appropriate to call them “writers” any more) will become highly-paid corporate “content design” consultants and form a new niche of documentation experts. If you’re just starting out your technical writing career you might as well start specializing in that direction.

(6) What’s your views on globalization, out-sourcing, and the way it affects technical writers in the USA and abroad?

Globalization and out-sourcing are the result of two relentless forces in capitalism: (1) The imperative to minimize production costs; and closely linked to this: (2) The imperative to replace labor-intensive methods of production with their capital-intensive counterparts.

Out-sourcing won’t go away. If anything, the trend will become even more pervasive. Whenever India (for example) reaches a wage-level approaching that of the West, other labor-markets will appear overnight and the job-migration will continue unabated. Don’t be surprised if one day India starts to lose documentation and call-service jobs to Mongolia, for example.

This forces the technical writers in the traditional tech-comm countries like the US, UK, and Europe to diversify their skills, on the one hand, and move up to more capital-intensive niches like structured authoring, on the other. Both moves will maximize the competitive advantage of a traditional technical writer. But those writers who continue to insist on “just writing” good-old user manuals will lose their jobs very quickly to outsourcing.

(7) What is your greatest passion with respect to technical communication?

After all is said and done, I think my greatest passion is learning new things, sharing what I know with others, and teaching technical communication skills to others. I really enjoy that learning-teaching dialectics.

So I guess it’s not a coincidence that I do have a technical communication blog catering to all levels of communicators (http://www.technicalcommunicationcenter.com/) as well as two online technical writing courses (http://www.technicalcommunicationcenter.com/online-courses/). In 2012 I’m intending to add at least two more courses to that list.

I think education and training are very important not only for our profession specifically, but for our survival on this planet as well in this age of increasing population and threatened scarce resources. From politics to daily life to documentation, I forgot the number of times when I witnessed precious potential going to waste for lack of education. The quality of our future depends on the quality of education we provide for our children and youth. That’s why as long as I live I know I’ll try to play my humble part in that learning and teaching process.

Dr. Ugur Akinci is a Senior Technical Writer working for Honeywell corporation. He has ranked 31st in MindTouch’s list of “400 Most Influential Technical Communicators”. He is the owner of Technical Communication Center, a blog dedicated to technical writing tips, tutorials, and trends.

Blog Sponsors

Blown Away by Author-it Aspect

Tom Johnson — Thu, 18 Aug 2011 15:58:30 +0000

Author-it Aspect

My colleagues and I were talking the other day about where we’re going to publish some help content. The scenario we’re addressing is a project that will be translated into 38 separate languages. Additionally, there are 28 roles for the system. This means there would potentially be 1,064 outputs (38 x 28), assuming help is to be specific to each user’s language and role. This is a tremendous amount of material to generate and keep track of, and the thought of it overwhelms me.

We’re implementing Author-it in my organization, and one of the technical leads showed us Author-it Aspect. Apparently this tool would allow us to publish all the content in the same output. Then through the user’s profile, he or she would see the help material that is relevant to his or her role and language. Rather than 1064 outputs, we’d have just one.

Here’s the demo that my colleague showed us. It’s a recorded webinar that I’m reposting here with Author-it’s permission.

This is the demo of Author-it Aspect. Watch about the first 5 min.

You’ll see that you can select options to see different views into the content. My understanding is that through an Author-it Aspect API, you can configure the views to your user’s profile (assuming the user logs in). Otherwise, if not logged in, the user would select the view from the Options menu. But here’s the point: it’s all the same help file. There aren’t hundreds of different help outputs to coordinate behind the scenes.

This seems like much needed technology that would simplify a lot of robust publishing situations. Granted, I think Aspect requires its own server and is somewhat costly, but the time it would save in managing the content might be worth it. Is anyone out there using Author-it Aspect? I’d love to hear about your experience.

For more information, see Author-it Aspect.

8/26 update: I recently learned that Aspect doesn’t support multiple languages as variants. This functionality won’t be available until version 6.0 of Author-it is released (within a few months).

Blog Sponsors

Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]

Tom Johnson — Mon, 17 May 2010 14:27:33 +0000

Let’s fast forward a year. Assume you have explored Swordfish and have hammered out a lot of help topics — nearly 200 help topics, in fact. You have met with subject matter experts and extracted critical information from them for many months. You have explored Swordfish inside and out, documenting every possible task and setting, and now you have a ton of content.

The help topics you created seem endless. You have checked their accuracy against the constantly updated Swordfish interface, and you have made a seamless flow from online help to PDF format. But now, at this moment, near the end of the project, you face the problem of content organization. You have so much content, it seems all one giant jumble of information. It needs to be organized better, with a sounder logic and structure, but how?

Attempting organization

In setting up my 200 help topics, I initially grouped the topics into various folders — for example, Covert Operations, Stings, Exchanges, Drop-offs. And then I titled the subfolders in each folder as “Basic Tasks” and “Advanced Tasks” to follow the model of increasing agent permissions. So the folder organization looked like this:

Covert Operations
     Basic Tasks
     Advanced Tasks

Stings
     Basic Tasks
     Advanced Tasks

Exchanges
     Basic Tasks
     Advanced Tasks

Drop-offs
     Basic Tasks
     Advanced Tasks

It soon was clear that no one understood what constituted a basic and advanced task, so I changed these subfolders to a grouping of content by role: “Super Agent Tasks” and “Regular Agent Tasks.” I structured everything in the help this way, assuming that this model would fit the majority of agents perusing the help. They could then navigate to the subfolders based on their known and probable role.

Covert Operations
     Regular Agent Tasks
     Super Agent Tasks

Stings
     Regular Agent Tasks
     Super Agent Tasks

Exchanges
     Regular Agent Tasks
     Super Agent Tasks

Drop-offs
     Regular Agent Tasks
     Super Agent Tasks

Feedback from both colleagues and users resisted these roles. “The folders are too general,” one colleague said. “I have no idea what Regular Agent and Super Agent Tasks mean. You need something more descriptive.” A user echoed the same thing, asserting that the folders were too general and vague.

Technical distractions

Release dates drew near. Although the folder naming conventions weren’t ideal, I was proud of the single sourcing model I had set up. The online help single sourced to a PDF printout without any modification of the PDF at all. In fact, I even set up a recurring job to automatically republish both the online help and PDF every day at 2 p.m. It was a completely hands-off, automated process.

But then something happened. A few days ago, one of the chief agents in the department mentioned he was preparing a presentation to a set of field agents, and could I show him where to print the quick reference guides and user manuals?

Gladly I showed him the links, but because I had a few days until the deadline, I decided first to read through the PDF, which previously I had hardly glanced at except to ensure proper formatting and PDF rendering.

Printing out the PDF, which essentially duplicated the online help but in print format, was 197 pages. I didn’t realize it was so long, but I pulled out my red pen and started to proceed through the topics with patience and anticipation.

Non-linearity and linearity

As I moved from topic to topic, I noticed that the topics didn’t flow well together. Some topics repeated information stated on other topics. Other topics introduced concepts in some places but didn’t include tasks related to those concepts until pages later, as they were interrupted by other topics.

Overall the content was too detailed, too wordy, and too long. I drew big red slashes on numerous pages and wrote “Cut” more times than I could count. I wanted a shorter reading experience. After page 50, I had read all I wanted to.

The chief agent’s assistant also agreed that she could not print 197 pages for each participant. The length seemed ridiculous. Was the application really that complicated?

Somewhere, something had gone wrong. I entered into the project with a couple of assumptions. First, I assumed help should be a mile wide and thirty seconds deep, that is, covering a wide array of topics in a brief way. Consequently, I had written dozens and dozens of topics that covered all kinds of scenarios. This might have been all right had I left the miles of topics in the online help, but I had also included these topics in the PDF.

Reading through the PDF, there was no flow, no tight coherence of ideas, no transitions from one idea and topic to the next. It was if someone gathered 200 Post-it notes written independently of each other and positioned them sequentially — and then was surprised when the content lacked flow from one Post-it note to the next.

I had another faulty assumption, one that I knew but had forgotten. Online help is a non-linear reading experience. A printed document is a linear reading experience. The two reading modes aren’t interchangeable. Reading through the PDF made that clear.

Crumbling organization

I noticed another problem in reading the PDF. The chapter titles Super Agent Tasks and Agent Tasks began to annoy me, even more now than before. What did they really mean? Nothing. As my colleague had pointed out, the titles only meant something if you knew what sort of tasks each role could perform (which I did).

But if you didn’t already know the limits of each role, grouping topics by role wasn’t helpful. You would only know to look in that role’s folder if you knew that role could perform that task. But most users wouldn’t know the tasks each role could perform. Many of them wouldn’t even know what roles the application had. So the folder names were somewhat meaningless.

The help file was falling apart on two levels now: poor folder/chapter titles, which left the organization of tasks vague. And also a hodgepodge of clashing topics in the PDF output, which didn’t result in a linear reading experience.

Blog Sponsors

Top Trends in Technical Communication

Tom Johnson — Wed, 23 Dec 2009 07:57:08 +0000

In a recent email to me, Jake from California (not his real name or location) writes,

I’ve spent most of today exploring the world of technical writing, and I find that you’re very central and visible. I’ve read, listened to, and watched a good deal of content you’ve produced, plus viewed snippets of threads on the STC listserv where you either weighed in or were referenced.

If I can prevail on you for just a few minutes of your time, I’d like to ask some advice. To summarize quickly, I decided on a writing project in the mid-80s that got me into PCs and DTP software. That led to steady work in software documentation for the next ten years with much of it overlapping the development of the web. I learned several tools for that, as well. My most recent job has taken me off in another direction, and I’ve lost my familiarity with this industry for a few years.

I’d really like to return to what I know and like best, and I know I have a pretty steep learning curve ahead. The nearest STC chapter is more than three hours away from me, and I don’t know how active they are. I was disappointed to see that the STC is having difficulties. I read David Farbey’s and your posts on it. Most of my time today was spent in gathering names of software applications currently in use to begin an investigation. And I looked on a few jobs sites, too. It’s been a busy day.

Could you advise me where to spend my time and energy? Besides your blogs and others I like it that I find, the TECHWR list, and possibly joining STC to gain access to their resources, how would I inform myself on current trends in documentation? When I entered the field in 1991, I did so because I had learned one software application and joined a local software user group through which a recruiter found me. I couldn’t be that lucky a second time! At the moment, I feel like I could spin my wheels for quite some time without getting anywhere.

Thanks for any nudge you might be able to give me.

Jake

I am always flattered to read comments like this. I don’t know what the experience is like searching for trends in technical writing, but it’s neat to think that I’m “very central and visible.”

I often respond to reader questions on my blog because other readers have the same question. What are the trends in the technical writing, what tools do you need to know, and how do you position yourself as a strong technical writing candidate in a competitive job market?

The technical writing tools question is always the hot button. I’ve learned to avoid tool discussions as much as possible. Even in my recent STC Screencasting webinar, I completely omitted tools, and someone still asked, What are you using to capture the screen? I said Camtasia Studio. Then I mentioned some other video capture tools for Macs and PCs, and within a minute, someone piped in to say that Captivate is far better than Camtasia … and so on.

Tools are an inevitable part of the job application process. HR departments perpetuate the need to know specific tools in part because IT jobs often require specific programming language skill sets. Nevertheless, the tools issue can be deflected or minimized as you start talking about the core issues and trends in the field. So without further ado, here are the top ten trends in technical communication that you need to be familiar with.

Top Trends in Technical Communication

I loosely ranked the top ten trends according to how I see their importance.

Trend #1: Collaborative authoring. Authoring projects are no longer written by a single author working from a single perspective. Robust projects require input from multiple subject matter experts, often based in various locations/departments describing different business processes that only a person immersed in that environment can know. You need to know how to harness and integrate information from multiple authors and pull them into one searchable source. For more information, see this post on Collaborative Authoring.

Trend #2: Social media. Twitter, blogs, podcasts, Facebook, Ning, LinkedIn, and the other social networks on the web are where conversations are probably taking place about products you document. Successful companies participate in social media because it allows them to interact with their customers, gather feedback, and strengthen relationships. For more information on social media and documentation, listen to this podcast with Anne Gentle about conversation and community.

Trend #3: Hybrid technical writers. Just knowing how to write won’t make you competitive. You have to wear multiple hats and become a hybrid. You’re not just a writer, but a writer/web designer, a writer/content strategist. You’re a writer/multimedia producer. You’re a writer/information architect/business process analyst. You’re a poet/programmer/QA tester/motivational speaker. For more on being a hybrid, listen to this podcast with Jack Molisani. Also listen to Bogo Vatovec explain that if writing is your only skill, you’ll soon be fired.

Trend #4: Globalization. You may work with a team distributed globally. But your products are often globally distributed as well. This means you have to simplify your language and write in a way that can be translated. You should be thinking of different cultures and how they might [mis]interpret your instructions or need more information in different areas. For more information, listen to Kirsty Taylor’s 2009 STC Summit session, Collaborating Around the World.

Trend #5: Multimedia. Screencasts are short video tutorials often streamed on YouTube or other video sharing sites (or simply played locally) that show users how to do tasks. Screencasts are part of the multimedia explosion of the web. They’re intended especially for visual learners and are usually narrated. For more on screencasting, you can see my slide deck from a recent webinar I gave on screencasting.

Trend #6: Single sourcing. Maybe single sourcing isn’t a new trend. Maybe it’s a holy grail that was never fully achieved. But knowing how to single source content within a project is essential. You have to know how to reuse content from online help into printable guides, at theleast. If you can single source more than that, more power to you. For more information on single sourcing, listen to a few perspectives on single sourcing from Michael Hiatt, Sarah O’Keefe, and Neil Perlin.

Trend #7: DITA. Darwin Information Typing Architecture is the latest XML standard that allows reuse on a robust scale. More and more tools are supporting the DITA standard. If you’re gearing up to do single sourcing and content repurposing in the big leagues (for example, the airline or pharmaceutical industries), DITA is a standard you may want to learn. For more information, listen to this podcast on DITA. Also, Sarah O’Keefe recently published a study about the rising trend of structured authoring that you may want to check out. (DITA is one way of doing structured authoring.)

Trend #8: Content strategy. Content strategy looks at content as a whole in every format (web, social media, product descriptions, instructions, forums, etc) and asks what the message is. Do we need it all? Are we diluting our branding and core message? For more on content strategy, listen to this podcast with Rahel Bailie and also check out Kristen Halverson’s book on Content Strategy.

Trend #9: The Cloud. More and more applications are becoming accessible from an Internet browser rather than requiring a local install. As an application in the cloud, help is also in the cloud, which means you should be able to update your materials in real-time. Your help can be web-like. You can also start taking advantage of all the web tools that can make your content sexy, such as jQuery. For more information, see Ben Minson’s post Time for Help to Get a New Wardrobe.

Trend #10: User-generated content. Rather than treating your users as passive consumers, you can empower them to add comments, become forum moderators, and contribute articles on a wiki. Users are your secret weapon, as long as you can find and foster the communities where they thrive.

If I could add one more topic, it would be intelligent content, but I already hit 10.

More Resources

Not enough for you? A couple of years ago Mark Lewis gave a presentation at the STC Summit called 10 Skills to Advance Your Career. He also included a nice handout. (And gave me permission to include both the PowerPoint and handout in this post.) His presentation is relevant here, since each of the skills he covers will make you a stronger candidate.

That’s a lot to focus on, I know. But more than learning Framemaker or Flare or some other help authoring tool (which one company may use while another rejects), I recommend becoming familiar with the core trends in the field and how you can help a company move forward in each of these areas.

Blog Sponsors

Podcast: The Myth of Single Sourcing

Tom Johnson — Tue, 22 Dec 2009 05:32:20 +0000

Download MP3
Length: 38 min.

In his controversial post, The Myth of Single Sourcing, Michael Hiatt explains:

Single-source publishing is a zombie idea that revives itself periodically and refuses to stay dead. Its zombie supporters chant its purported benefits as a “write once, publish to many” promise and ploddingly follow it as their ultimate goal for mechanized authoring and machine translation. As an object-oriented writing methodology, it is as human as present-day robot technology—good only for conveyor belt assembly or specialized tasks, and always very expensive to implement. Single-source publishing lacks purpose in today’s world of information turnover and the dynamic nature of the Web 2.0 moving to Web 3.0 landscape.

In other words, single sourcing your content across the enterprise is an idea that simply doesn’t work. I responded to the post and had a lively exchange in the comments, so I decided to interview Michael for a podcast.

In this podcast I talk with Michael about single sourcing, collaborative authoring, mashups, help authoring trends, and other topics. You can follow Michael’s blog at Mashstream.com.

(Note: We had a brief Skype issue at the start. The audio gets noticeably better at around the 5 minute mark. It’s actually a great example of the clarity that the double-ender recording technique provides instead of just using Skype to record.)

Blog Sponsors

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

Leaning Towards Longer Topics and Shorter TOCs

Tom Johnson — Tue, 23 Sep 2008 04:36:09 +0000

Everyone knows it’s a good practice to chunk your help material into discrete topics, but how granular should you chunk it?

Take a look at this Microsoft Word 2007 help topic on inserting headers and footers.

Example of a Quick Menu from Microsoft Word's Help on inserting headers and footers

Although inserting headers and footers is the main task, the topic really has 11 related tasks:

Insert the same header or footer on each page
Make the first page header or footer different from the rest of the pages
Use no header or footer on the first page
Make the header or footer different for odd and even pages
Make the header or footer different in each section or chapter
Change the contents of a header or footer
Insert a page number
Insert the file name of the document
Insert the document title, author’s name, or other document property
Insert the current date
Remove the header or footer

The author could have created 11 separate topics. Do you agree with Microsoft’s decision to group all of these subtasks into the same topic? Or would you rather explore each subtask as a separate topic in a table of contents?

Although the practice of single sourcing encourages chunking of tasks, if you won’t be reusing the subtasks or related tasks independently, there’s little reason to separate them out into discrete topics. Forcing all of these subtasks into separate topics would severely bloat the table of contents (TOC), rendering it not only less usable, but also more intimidating. Your application’s apparent complexity would magnify.

Separating each subtask into its own topic often forces users to click in a non-linear pattern from topic to topic as they search for the right task. This nonlinear clicking can give users a headache. It’s part of the reason why reading online is more strenuous than reading a book. Books provide more of a hierarchical layout and logical progression of ideas. In contrast, the web is a scattered maize.

Consolidating subtasks into one topic also improves the user’s ability to find topics. With fewer topics in the TOC, the user can actually browse the TOC and find the right topic. But even if the user reverts to keyword searches, the longer topics will have greater keyword density and more likely rise to the top in search results.

I sent a question across Twitter the other day asking whether anyone had done research into this issue, and Brenda Huettner pointed me to a Web Usability Guidelines reference book. Chapter 8 echoes Brenda’s response that “it depends.” The authors say that older people are slower at scrolling, but comprehension may be better because the user remains on the same page. Here’s an excerpt:

Guideline: Use longer, scrolling pages when users are reading for comprehension.

Comments: Make the trade-off between paging and scrolling by taking into consideration that retrieving new linked pages introduces a delay that can interrupt users’ thought processes. Scrolling allows readers to advance in the text without losing the context of the message as may occur when they are required to follow links.

However, with pages that have fast loading times, there is no reliable difference between scrolling and paging when people are reading for comprehension. For example, one study showed that paging participants construct better mental representations of the text as a whole, and are better at remembering the main ideas and later locating relevant information on a page. In one study, paging was preferred by inexperienced users.

Sources: Byrne, et al., 1999; Campbell and Maglio, 1999; Piolat, Roussey and Thunin, 1998; Schwarz, Beldie and Pastoor, 1983; Spool, et al., 1997; Spyridakis, 2000.

In other words, each time a page loads, you interrupt the user’s thought process. By remaining on the same page, the user can better grasp the concept as a whole.

Thanks for the resource, Brenda! In the studies, the content consisted of web pages rather than help material. Some of the examples for scrolling depict long, sophisticated pages — quite a bit more hairy than the Word example above. Still, I agree with the general findings and think they apply to help authoring.

My colleague Ben Minson, however, raises an important objection to long topics. He says,

In reality, people don’t want long topics. They want to think that procedures are short and simple. Long topics intimidate people and make them reluctant to consult the documentation in the future. (“Long Topics: A Help Author’s Crime Against Humanity“)

I agree that no one wants to be confronted with a massive topic when all they need is information to complete simple task. However, adding a quick topic menu at the top, similar to the following image, seems to solve that problem, doesn’t it? The user can jump immediately to the relevant topic, rather than meticulously scrolling down and checking each heading.

[image title="Example of a Quick Menu" size="full" id="2017" align="left" linkto="viewer" ]

Overall, in my experience, it’s easy for a help’s TOC to grow successively larger as you think of more and more scenarios, possible tasks, and concepts to explain. But if you reach the end of the project and see that your initial 50 topics have grown to 250, I think something’s wrong. Most applications aren’t that complicated. When users expand the TOC and find a seemingly infinite number of topics, it’s the equivalent of the disheartening “thud” from a long printed manual.

Podcast: Repurposing Content for Multichannel Publishing (Single Sourcing)

Tom Johnson — Fri, 19 Sep 2008 06:50:17 +0000

Download MP3 (right-click and select Save Target As to download)
Duration: 60 min.

In this podcast, Liz Fraley, founder of Single Sourcing Solutions, talks to the Intermountain STC chapter about “Repurposing Content for Multichannel Publishing.” See this flyer for a more detailed description of the presentation.

Liz Fraley is the founder of Single Sourcing Solutions. You can read her full bio here. To contact Liz, send her an email at liz.fraley@single-sourcing.com.

How Much Should You Document? Everything? Strategies for an Agile Environment

Tom Johnson — Wed, 10 Sep 2008 03:19:28 +0000

In a recent IT Author podcast (“Documentation and Agile Development“), Alistair Christie and Graham Campbell talk about agile development and its impact on documentation. One consequence of working in an agile environment, they say, is the need to prioritize your documentation, to deliver instructions for only the most important or confusing features.

Presumably, some agile environments move so fast, you have to triage what you document because there’s no time to document everything.

How much should you document? Everything?

Alistair explains that you can’t document everything, and he quotes from Martin Fowler’s “The Almighty Thud.” Fowler, however, takes the argument one step further, arguing that you shouldn’t document everything. Fowler writes,

If you document everything, you are giving everything an equal weight. Do that for a complex system, and you are buried in detail. In any system there are some aspects that are more important than the others, key aspects of the system that once understood, will help someone to learn more. The art in documentation is to find how to document these aspects as clearly as possible. In this you emphasize these areas, and leave the details for the code.

If you document everything, you end up giving everything equal importance and losing focus on the key tasks and concepts users need to learn. You need a focal point, a selection of core tasks that receive prominence and make everything else intuitive.

Fowler continues, citing his own approach to the article he wrote as an example:

As I started to write this article I was overwhelmed by the things I could talk about. Lots of anecdotes and tips came to mind. But I know that to get you to read and remember this article I could only talk about a few of them. I had to select the key things that I had to mention. Communication is all about that. The key to good communication is to highlight the important things to say. Saying everything is not communication. That just passes the selection of the important things onto your readers, and discourages them with a heavy document. That selection of information is one of the most important parts of communication, and it is the responsibility of every designer.

I agree that selection is key to crafting any article. Were his article 20 pages, I wouldn’t have read it so eagerly. Instead, because it’s 2 pages, I did read it.

Alistair says that when you give someone a huge manual (one that makes a thud when you set it down), it makes the user’s heart sink. “They don’t think, Oh, that’s great. No, they think oh, This looks grim.”

Bloating the table of contents with dozens of non-essential topics reduces the focus on what customers need to be concerned about. Each additional word you add dilutes the importance of the other words. “The more you document, the less people read,” Alistair says.

We all know that if you give someone War and Peace, they’ll probably never read it. But give them a short story and they read it the same afternoon.

No one disagrees with brevity. Almost all users want concision. However, writing an article is different from writing a help system. In a help system, I do think almost all the features should be documented — somewhere.

If you limit the help topics to just the core topics, what happens when the power users search for an advanced question and find nothing? What happens when Joe user wants to know how X widget functions? Is our response simply, “Sorry, we didn’t think that feature was important enough to document”?

Fortunately, this whole dichotomy between (a) documenting everything and overwhelming the reader and (b) selecting what to document and risking absent information is an Either-Or fallacy. It is possible to both document everything and give the user a brief guide. Simply, document everything in the online help. Then create a quick reference guide to give to the user.

Am I missing something?

To avoid the disheartened look on a user’s face as the two inch manual makes a thud on his or her desk, reduce your printed manual to a much smaller subset of the online help, rather than duplicating it. Remove all the low-priority topics. Let the reader know that full documentation is in the online help.

Since users don’t typically read manuals anyway, they’ll welcome this approach. No one has ever said to me, Tom, this guide feels a little thin. Couldn’t you add more to it?

Fowler’s advice to avoid documenting everything may reflect what he was documenting as well as his time. Fowler was documenting code, which has layers upon layers of depth. But he didn’t say to leave out documentation, just to “leave the details for the code.” You can add little notes here and there in the code using slashes.

Also, Fowler wrote his article back in 1997 — more than 10 years ago. At that time, I’m not sure he had all the single-sourcing capability we currently have. Perhaps producing subsets of documentation (or multiple manuals for different roles) was too difficult.

I’d be curious to hear your approach. Are you over-documenting? What’s your approach to reducing the “thud” while still delivering complete documentation?

Additional Resources

Listen to this Boagworld podcast for details on agile methodology.

Read this post on extreme technical writing from a tech writer’s point of view.

Resources for Single Sourcing Projects

Tom Johnson — Mon, 01 Sep 2008 06:59:12 +0000

Resources for Single Sourcing Projects

I'd Rather Be Writing » single sourcing

Interview with Ugur Akinci about Technical Communication

Blog Sponsors

Blown Away by Author-it Aspect

Blog Sponsors

Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]

Technical distractions

Non-linearity and linearity

Crumbling organization

More content, but no space for it

Blog Sponsors

Top Trends in Technical Communication

Top Trends in Technical Communication

More Resources

Blog Sponsors

Podcast: The Myth of Single Sourcing

Blog Sponsors

Why Help Authoring Tools Will Fade

Blog Sponsors

Leaning Towards Longer Topics and Shorter TOCs

Podcast: Repurposing Content for Multichannel Publishing (Single Sourcing)

How Much Should You Document? Everything? Strategies for an Agile Environment

Additional Resources

Resources for Single Sourcing Projects