I'd Rather Be Writing » hats

Technical Writing – Making Resolutions for the New Year

Tom Johnson — Mon, 27 Dec 2010 06:35:05 +0000

As 2011 approaches, Lynda at WritingAssist.com encourages technical writers to make technical writing resolutions for the new year:

A new year means you get the chance to do things over, to do things better. Whether you’ve been happy with your technical writing team or you think things should improve, it’s time to look back on the past year to see what needs to improve and what needs to be removed from your company for the year ahead. (Technical Writing – Making Resolutions for the New Year)

A few of her recommendations were on the conservative side, in my opinion. Update your software, modernize your style guide. Nevertheless, this got me thinking about new directions I’ll take in 2011. I’ve been moving in some of these directions for a while. Here are the top 10 technical writing resolutions I have for 2011.

Use wikis rather than traditional HATS to author help content.
Give users quick reference guides rather than long printed guides.
Include more visuals, especially concept diagrams, in my help content.
Master Adobe Illustrator and increase my understanding of visual techniques.
Read more of my RSS feeds online and use them as a way to generate ideas for posts.
Start negotiating with project managers using an official user education plan rather than informal agreements.
Implement an official workflow of post-release documentation efforts based on user feedback, bugs, questions, and other unforeseen situations.
Solidify our team with standard approaches and processes as well as build unity through proximity.
Contribute to corporate blogging efforts for IT site.
Interact with community through forum, feedback, and other participation channels; stay abreast of needs and questions.

These aren’t so much resolutions as directions I’m heading.

Blog Sponsors

From Overlooked to Center Stage [10]

Tom Johnson — Sun, 18 Apr 2010 06:54:09 +0000

Epiphany: Cross Pollination

Ultimately, what my colleagues had to say did have merit. There is a point that, in playing too many roles, you spread yourself too thin. You compromise your specialization and expertise as you step into unfamiliar territory. There is a limit to the number of roles you can play, and perhaps I had stepped over that limit.

But I believe I also experienced the idea of cross-pollination. In biology, cross pollination refers to the mixing of species by taking pollen from one flower species and spreading it to another.

In an intellectual sense, cross pollination refers to the advantages that come through diversity of perspective, background, experience, knowledge, ideas. When you bring professionals together from “different species,” so to speak, they cross pollinate and create new ideas, hybrids, innovations, and advancements. But if everyone always works within his or her same knowledge domain, the diversity doesn’t often cross-pollinate. If people do their jobs and just report to the project manager, they remain in silos.

On the other hand, when you have these professionals walking in each other’s shoes, playing each other’s roles, seeing problems in unfamiliar domains from new perspectives, insights to problems come more easily. New approaches and methods appear more readily.

It’s the same perspective you get when you have others critique your documentation. The more unique a reader is from you, the more advantageous his or her perspective will be. The reader can show you what you can’t see. The reader has a perspective you can’t access yourself.

As I as writing one day, I realized that my extension into these other areas had made me a much faster, more efficient writer. It made me more aware. From my interactions with customers, I could better imagine personas. Often after writing a topic, I would picture that frazzled user who had me on speed dial and wonder if he would actually get what I was writing. I could think about specific users, like the people in Europe who traveled constantly, or the executives in audiovisual, or the mission presidencies in Russia. I could step inside the heads of the users better because I had actually interacted with them. The questions they would ask would naturally be on my mind as I wrote documentation.

The bugs I was logging integrated me with JIRA. I knew how to look and see if bugs and quirks would be fixed or not. I learned how to speak and communicate with developers. I could also see bugs where QA engineers could not see them, because I brought the perspective of documentation as I explored the application. I could anticipate possible problems on different screens in ways QA couldn’t. And as I applied the tools of documentation to my bug logging, adding screenshots with callouts and videos, I introduced QA to new methods that they adopted.

As I created scripts for my videos, I began to see how the dry, technical language in my help topics contrasted with the lively, conversational voice I had to implement in the video scripts. As I wrote, I often imagined myself speaking to the user in a video script. It’s amazing how conversational that helped me to be.

Because I was more of a presence in meetings and outside my cube, people trusted me more. They more freely communicated with me more to relay problems and issues. I could be a better wiki manager because I was accustomed to interacting with others, giving guidance and feedback in tactful yet assertive ways.

All of these ancillary activities weren’t detracting from my ability to do my job. Instead, they were enhancing my ability to do my job. I was becoming a better technical writer not in spite of these other roles, but because of these other roles I filled.

Given this cross-pollination effect, I openly welcomed the new roles I would play. Each new role would give me a new perspective, a new pair of eyes. And the more I could see the project from different perspectives, the more of an asset I would be to the team and to the success of the project.

To come back to a few quotes at the beginning, I mentioned some experiences from disgruntled technical writers on a guest post called The Raw, Unvarnished Truth. Last week someone posted the following comment:

I have been a technical writer for over 22 years. During the 1990s, at the time of the dot.com bubble, the field was exciting and challenging. Now, with the bust, technical writers often do nothing more than edit dreary procedures. I have found that working for small or medium-sized companies is much more exciting than working at a large corporation. …

The writer continues on for a bit after that to relate the drudgery of working for large companies. But let’s look at the sentence about working for small or medium-sized companies.

Why is it that technical writers working for small or medium-sized companies might find the work more exciting? Although the user doesn’t say it, I know why. In small companies, you wear many hats. You play many roles. You’re not pigeonholed into one specialized role all day long. Sometimes you’re the marketer. Other times you’re the instructional designer. Or the tester. Or customer support. Or the interaction designer. You probably interact with the CEO on a regular basis.

I recently interviewed Mike Hamilton for a podcast, and he said he started his career as a physicist and ended up at a software company. I asked him how many different roles he played at Madcap. His response:

Pretty much any hat that’s not being worn by somebody else the day we need something to happen.

I’d bet that almost every one of us transitioned into technical writing from some other career. Maybe not physics, but perhaps like me, coming from teaching and copywriting, or something similar. At some point in time, we decided to put on the technical writing hat and fill the technical writing role. Role playing is something we naturally do. We’re not technical writers playing other roles. We’re people playing many roles, one of which is technical writer.

Blog Sponsors

From Overlooked to Center Stage [9]

Tom Johnson — Sun, 18 Apr 2010 06:38:48 +0000

Crisis Point: Problems with Multiple Roles

As my attempt to fill the wiki role failed, I started to realize how busy I had become wearing all of these hats. It seemed that I was always logging bugs, answering phone calls or responding to emails, or attending this and that meeting, championing for a redesign of a page, or coordinating with projects. The core help I was supposed to deliver wasn’t getting done.

I knew that I had been sloppy and careless in a lot of the help topics, and I just hadn’t had the time to go back and carefully review all the content for the upcoming releases like I wanted to. I was being stretched in so many directions, it was hard for me to do what I was initially hired to do: create help material. At times I would refuse to answer simple emails because I knew it would take me out of my rhythm and make it harder for me to get my work done.

I started to reach my limit when one frazzled user put me on speed dial. He called me what seemed like several times a day over the course of a couple of weeks, and each time he called he would ask questions and ramble and complain.

I realized that if just three or four more users were like this also decided to put me on speed dial, I wouldn’t be able to get anything done. Our user base was expanding with the new release, and the project manager was now asking me to creating marketing slicks and big picture workflow diagrams that they could pass out to users. I just didn’t have time to get to all of this.

When people made these requests, I would kind of nod and say okay, I’ll do it, but as the release date approached, I was so busy setting up my online help file and adjusting the style sheet and the targets and integrating the videos and putting everything else into place, the days ended before I could dive into the actual content.

It wasn’t just a matter of time, though. I also started to question the appropriateness of filling so many different roles. Although I have good common sense, I don’t know a lot about usability, quality assurance, project management, e-learning, or even live training. I do know documentation well, and I keep up with the latest trends and best practices in this field. Was I doing a disservice to my organization by filling roles about which I had little professional expertise?

I started to think back to a conversation I had had with another QA engineer when we used to drive in together to work. We must have had this conversation at least half a dozen times while driving at six in the morning. I would complain that there weren’t enough technical writers working in our organization. I said a ratio of about 4 technical writers for 600 IT people was ridiculous.

My QA friend kept wondering why, given our limited technical writing resources, I would spend time filling other roles — especially if we already had people designated to fill those roles. If I truly wanted to expand my influence and provide documentation for all of these applications and sites that lacked help material, I wouldn’t try so hard to do QA. I would let QA do QA. I wouldn’t try so hard to do design. I would let interaction designers do design. I wouldn’t try to provide support. I would let the service desk provide support. And so on.

He even said I shouldn’t try so hard to write comprehensive documentation. I could just create quick reference guides and jump from project to project to project, providing only as much help as 80 percent of the users would actually need. But regardless of my approach, overall he said that it wasn’t efficient for me to do the roles that other people had been assigned to do. Doing so created unnecessary overlap.

I thought about this, and wondered if in fact wearing multiple hats wasn’t a good idea after all. Perhaps I should have just remained in my cube and quietly created help materials in the most efficient way possible. Unless I knew something about these other roles, these other hats I was wearing, I perhaps shouldn’t wear them. After all, ultimately it wouldn’t be that helpful to the team if i were exerting my influence in areas that I knew nothing about.

Finally, what did playing these other roles ultimately do for me? It seemed that at the end of the day, I was still evaluated on the help material I produced, not the number of bugs I logged, not on the number of design suggestions I championed, not on the number of users I helped. Those seemed to be invisible efforts that, although appreciated, ultimately remained somewhat invisible. But you could hold a manual in your hand. You could see an online help system. You could watch an instructional video. And you know who produced the material, and you can evaluate the employee based on those products.

I asked my colleague what he thought about playing multiple roles. Was it a good idea?

Paul Person (“doc guy” in the Flare forums), said it’s good to fill other roles as long as you’re able. But you can’t really keep up your own knowledge about how to be a good technical communicator if you’re spread so thin in other areas. If you’re constantly moving into other areas, you suddenly don’t have time to keep up on the latest trends and best practices in your own field, let alone in the other fields.

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.