I'd Rather Be Writing

A Reverse Approach to Help Authoring: Writing Documentation Post-Release

Tom Johnson — Thu, 02 Feb 2012 06:33:20 +0000

When I first started as a technical writer, a senior writer taught me how to write documentation. Her approach, which aligns with the traditional way of doing technical writing, generally followed these steps:

Get involved as early as you can in the software development process. As soon as prototypes are available, or a functioning development environment, start the documentation process.
Think of all the main tasks users will do with the application. Make a list of the tasks and begin documenting them in careful detail.
As the application nears release, finalize your help material so that it’s ready when the application launches.
Once the application launches, move on to another project.

This traditional method of writing documentation places all the work before release. Sometimes I think the bulk of documentation should be written after release. This “reverse method” aligns more with support center philosophy. Some support centers believe you shouldn’t write anything until a user asks a question. Only then do you begin to document answers.

With a reverse approach to documentation, you place more emphasis on the help material after the release rather than before.

But you might object and say that our job is to anticipate the user’s questions and pain points so that when they do search the help file, the answers are there waiting. This in fact is Ginny Reddish’s premise in Letting Go of the Words. She encourages us to imagine a conversation with the user, anticipating their questions and responding as if in conversation.

I think imagination, even user interviews, are good techniques. However, too often I skip over this. I end up giving nearly every topic equal attention, documenting with careful detail both the obvious tasks and the difficult tasks. My imagination is usually an extension of the product manager’s vision and understanding, which I inherit from dozens of project meetings. The closer and more involved I get into a project, the less clearly do I see all the assumptions I’m making, the workflows I’m immune to, how blind I’ve become. No one can predict the future. How often have our anticipations and imaginations perfectly matched user reality? Do we even know the user’s reality?

With the traditional method of documentation, after the application is released, I’m not as closely involved with the project anymore. I don’t have my nose in JIRA; I’m not carefully monitoring all the incoming feedback. In my mind, I’m done. User pain points and frustrations often go unnoticed, while my attention shifts to new projects. I may add a topic here and there, or add some more detail, but by and large, documentation is mostly done when the application is released. I think that’s a harmful mentality that might be cured by a more reverse approach.

Let’s rethink the model. With a post-release documentation emphasis, the technical writer pays careful attention to every incoming question, comment, and feedback item from users. Whether through support center calls, forum questions, feedback emails, webinars, or other channels, the technical writer carefully monitors each question and begins building the help material from these questions. User feedback drives and shapes and structures the help material. It determines what we write, how much emphasis topics receive, and how visible we make those topics.

Now I’m not an extremist. I know that some help material is necessary when an application is launched. Quick reference guides and some basic help material would probably suffice. It would give something to the user to get started and not feel alone or abandoned. In some cases, a short series of video tutorials might also be helpful. After all, users need the most help when the application is newest to them, that is, when it’s first released. Abandoning the user in their time of greatest need may seem somewhat cruel and unproductive. I’m not saying no documentation should be written prior to release.

And yet, the long help file can wait. Wouldn’t we be much better to start writing help in an intensive, 100% heads-down manner during alpha and beta testing periods, and then during the first month of release? After all, how much time do we waste trying to figure out how a partially-built, bug-ridden application works in an unstable development environment? Wouldn’t our time be better spent waiting for the application to reach a near-production level, and then once that level is reached, focus all our energy on creating help material for it, based on questions and issues and frustrations users are experiencing?

Without a launch date for an application, there’s no clear date when documentation is done. In this post-release, reverse model, documentation can keep growing as long as users continue to ask questions and experience frustrations. Documentation is probably finished when the incoming feedback dies down, when most of the incoming questions can be answered with simple links to answers in the help.

Feb 3 update:

Check out this video from Greg DeVore that expands on some of the points I make in this post:

For a contrasting perspective on the idea of reverse documentation, see this post by Kristi Leach, When is it time to hire the technical writer?

Blog Sponsors

Brainstorming Solutions to Volunteer Management/Engagement

Tom Johnson — Wed, 01 Feb 2012 15:56:27 +0000

I am constantly reflecting on the answer to this question: How can I draw upon the enthusiasm, intelligence, and skill of willing volunteers all around me to take our organization’s site to the next level? This goal mostly relates to my involvement in my organization’s technology blog, which has about 80 volunteer writers.

In my post about what I learned during 2011 as a technical communicator, I wrote:

Community collaboration is extremely tough to pull off. I can’t just assign a volunteer writer a topic and let them run with it. I usually have to either gather the information from a subject matter expert or connect the volunteer with a subject matter expert — and then see them through the process with more hand-holding than I want to provide. Still, community volunteers can generate momentum by the sheer number of assignments I have to follow through with. Overall, I have no idea how to engage community volunteers in an effective way, but I think I can eventually figure a strategy out. (See What I Learned About Tech Comm During 2011.)

In response to this post, Saul Carliner added the following insightful comment:

But the challenges of working with “volunteers,” is one that is rarely mentioned when discussing SME-authored and user-generated documentation. Having had worked with volunteers in a number of sectors over the years–from work-related ones to community ones–the issue of volunteer management is one that still challenges all of them. Incentives and clarity help, but not always in the way intended. Even in areas that have years of experience with volunteers, it’s more of an art than a science. Just because we’ve moved to community-based approaches to documentation and the wikipedia has been successful doesn’t mean that other ventures don’t involve nurturing.

The last sentence particularly stands out. Yes, many social ventures (such as Wikipedia and Digg) have been hugely successful. But that doesn’t mean applying the volunteer model to tech comm is a process or technique we understand. It’s an art, and one that most community managers still struggle to figure out.

The topic isn’t just limited to volunteer engagement. SME-authored documentation, as Saul mentions, also fits into this genre.

In a series of questions I responded to on Ugur Akinci’s blog, I reflected at length on what is the most significant change in the field of technical communication. It fits right in with collaborative efforts and social intelligence. Here’s an excerpt of my response:

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

… The greatest transformation yet to come is to drop the single-author paradigm of technical writing and to embrace the way information flows on the web. … For years help authoring has consisted of one person (or just a few people) writing help material. When content comes from one person, the content is usually limited in perspective, accuracy, and applicability. Writing needs to become much more collaborative, and not just from inside the corporation, but outside as well. Documentation is never finished. When I log off for the day, someone out there may be contributing to the documentation, making it evolve, adding sections, correcting errors, expanding on special cases, and so on.

It’s engaging to come into the office in the morning and review the latest changes to the wiki, to find that someone added a new section, or a new page. We no longer have documentation as static, standalone files that are written in haste by one technical writer and then “finished” as he or she moves to the next project. Documentation is a living, breathing body of information – like the web. The web is in constant flux. It’s full of a whole landscape of people – trolls, spammers, forum champions, lurkers, relentless volunteers, bloggers, programming whizzes. All of these people, like characters in a circus, come together on the same stage, interacting with each other in rich, multifaceted ways. Sometimes these interactions are exciting, other times they’re frustrating. But either way, documentation evolves to become more web-like in the ebb and flow of information.

This ebb and flow of information is what I find most rewarding about technical communication. Information no longer emanates from one source but rather connects into a greater body of people. This is the genius of the web. The web thrives because of this content interaction — one person building on the ideas of another in collaborative, interactive ways. (Read the full interview on Ugur Akinci’s blog.)

Let’s come back to the original question. How can you harness the enthusiasm and talent of volunteers in productive ways? The answer to this question wouldn’t just be a neat technique to enhance productivity; it would change everything about my job.

The problem is not content strategy; it’s content tactics. The strategy is clear: draw upon the talent and enthusiasm of willing volunteers to write high-quality content. The details of how remain a mystery. Let me continue my brainstorm.

Challenges

Several main challenges make this a difficult problem:

Volunteer writers often don’t have the information necessary to write articles.
SMEs with the knowledge often don’t have the interest to write articles.
Content that volunteers write, even if informed, often needs significant editorial processing before it’s ready for publication.
Writing assignments often need more detail before you can assign them to volunteers. If you can only gather this information internally, it makes it difficult to assign to volunteers.
The remote distance between headquarters and volunteers makes collaboration and communication more difficult.

Known Principles that Work

Now that I’ve outlined the challenges, let me also outline what I’ve learned about volunteer engagement:

People are much more likely to accept invitations when invited on a personal level.
People are much more likely to accept invitations when they have a relationship of trust with you.
People need a clear understanding of what you want them to do.
People need deadlines to understand when you expect them to finish their assignments.
People need regular communication so that you can address issues and other concerns that might be obstacles.
Communicating on a personal level, building trust, establishing deadlines, providing detail, etc., takes significant management time.
People need opportunities to pursue their strengths. Not everyone is a creative writer. Many people function better as editors.
People need access to information, people, and meetings to write the content that is expected of them.
Content often goes through successive levels of edits before it’s ready for publication.
People have a limited amount of time to work on articles they are not getting paid for.
People like to feel that their contributions are valued, not wasted.
Coordinating, tracking, commenting, and following up on assignments for scores of volunteers requires an advanced system to manage all of this information.
People often want to get something in return for their volunteering, such as more experience, understanding, improvement, portfolio samples, and more.
People often overestimate their writing abilities.

Formulating a plan

I recognize that my brainstorming and analysis is specific to my own volunteer situation, and one situation may vary dramatically to the next. Hopefully the tactical plan I form may be of interest to others who work in other volunteer situations, even if the details vary. Given the challenges and known principles, what would work well for success?

Here’s are a few potential first steps:

Step 1. Create a body of work that volunteers can do. This means crafting assignments that are important and worthwhile. Creating a body of work may be the most difficult of all steps, as this requires me to add detail and potentially outlines to topics. Sometimes I may only have an idea for a story, or a name to contact, not an actual story in hand. But having a tenuous idea doesn’t work well for volunteers, who may be playing guessing games at what I want. The details of the assignments need to be clearly spelled out. Each writing assignment needs to have a basic level of clarity to be something that users can actually accomplish. Contact points, key messages for the article, length, tone, and other details should be clearly defined.

Step 2. Personally invite volunteers to act. The second step would be to personally invite volunteers to work on the tasks they’re assigned. The invitations should ensure that the writing assignment is a good fit for the volunteer (that is, matching the volunteer’s strengths and interests), that the volunteers have a good idea of what you expect, and the due date.

Step 3. Regularly review, track, and follow-up with assignments. It would be a good idea to review all the items stored in the system (in my case, JIRA) on a daily basis so that I don’t let some assignments languish and become forgotten. Volunteers may run into insurmountable issues and challenges; they may realize the assignment isn’t a good fit for their interests. By following up and checking in regularly with volunteers, I also demonstrate the value and importance of the assignment.

Step 4. Have volunteers edit volunteer writing. This is one of the steps that I’ve never implemented, but it might be good to have volunteers edit other volunteers’ writing. Writing often needs successive levels of editorial review. I could provide some quick comments and feedback, and then either have the volunteer make revisions or pass it to another volunteer to make edits, and then potentially to another volunteer. This way by the time the writing falls on my desk, it’s already to a level that is near publication quality. In some situations, I could ask SMEs to write content and then pass it along to volunteer writers to edit.

Step 5. Communicate regularly. Without regular communication, people lose interest. They quickly drop off. The communication also helps build trust, and people may feel as if they’re learning more from discussions. It’s not possible to build a lively community without regular engagement through e-mail and other online interactions. Perhaps contributing an e-mail a day may go a long way toward building trust and helping volunteers feel that they’re getting a lot out of the experience.

Conclusion

No system works if one doesn’t use it. These five steps aren’t rocket science. I could probably have a decent amount of success implementing them. The problem is maintaining regular activity, sticking with the system week after week, especially when other, higher internal projects get in the way. This is perhaps why breaking the tactics down to even a more concrete, daily to-do list might be a good idea.

I’m interested to hear what strategies you use for managing volunteer writers.

Blog Sponsors

Messages from Sponsors — January 2012

Tom Johnson — Mon, 30 Jan 2012 15:06:06 +0000

Below are a few messages from my blog’s sponsors. Check them out and see if any interest you. Many of them have upcoming webinars.

News from Madcap

MadCap Software is pleased to present free live webinars from industry experts covering a variety of topics essential for today’s technical writers. Sign up today to advance your professional skills and learn about the latest trends in technical communication.

Moving from FrameMaker to Flare | Feb 7, 10:00-11:00 am (Pacific Time)

Are you using FrameMaker as your primary authoring tool? While Frame is great for book publishing, it requires separate tools and plug-ins to single source content for the web. If you are tired of the expense and the headache of using multiple tools, consider switching to MadCap Flare.

Flare matches and exceeds FrameMaker’s best features, including variables, snippets (equivalent to text insets), conditions, and versatile cross-referencing formats. And Flare doesn’t restrict you to a linear, book-based model. You can manage content at the topic level and build multi-sectioned, double-sided books or websites and knowledge bases. Your choice.

Join Eddie VanArsdall as he demonstrates how you can adapt your FrameMaker workflow to a full-on, single-sourcing solution with one tool: MadCap Flare.

Presenter: Eddie VanArsdall, Content Strategist / Technical Writer

Making Your Content Mobile | Feb 23, 10:00-11:00 am (Pacific Time)

This webinar will provide an industry overview of moving different types of content to the mobile environment. Specifically, it will cover developing the following for the mobile environment: (1) HTML content, (2) PDF documents, (3) WebHelp, (4) e-books, and (5) e-learning courses.

Join Nad Rosenberg as she discuss technical issues, usability, and legibility as well as unique problems and solutions.

Presenter: Nad Rosenberg, President, TechWRITE, Inc.

Importing Microsoft Word Files into MadCap Flare Projects | Mar 19, 11:00-12:00 pm (Pacific Time)

Need to import Word files into a Flare project but you’re not sure what Flare’s Word import options do? Or why old and, apparently, well-behaved Word files give odd results when imported into Flare? This webinar addresses both questions.

Flare has a powerful set of Word import features that let you automatically break Word files into topics on import, specify style equivalents between Word and Flare (called “mapping”), and more.

Join Neil Perlin, MadCap-Certified Flare and Mimic instructor and consultant, in this webinar that walks through the process of importing Word files into Flare. We’ll look at the mechanics of the process and discuss the kinds of problems that occur in Word files and what to do to fix them.

Presenter: Neil Perlin, Flare Consultant, Content Strategist, Mobile Developer, Hyper/Word Services

For more information on our live and recorded webinars, please visit:

http://www.madcapsoftware.com/demos/webinars.aspx

News from Dr. Explain

Dr.Explain 4.5 Automates Help File Creation

Unique to Dr.Explain is its innovative approach to creating help documentation much quicker than with other tools. The program parses a live application and automatically produces screenshots of its windows along with a sequence of explanatory callouts for each control.

Watch the video press release about new features of Dr.Explain 4.5:

Annotation Template Editor is one of the coolest new features of the new release. It allows to create callouts of any design, complexity & style. Now you can prepare amazing annotated screenshots and graphics and insert it into your help documentation in a single tool. Dr.Explain produces documentation in the HTML (on-line manuals), CHM (MS Windows® help files), RTF, and PDF formats from a single source.

More information on Dr.Explain: http://www.drexplain.com.

Download a free trial: http://www.drexplain.com/download/. A free license for reviewers, editors and bloggers is provided on request.

News from Scriptorium

Thinking about content strategy? Check out Scriptorium’s latest webcast recording:
http://www.scriptorium.com/2012/01/webcast-content-strategy-in-technical-communication/

Coming attractions:

January 31: Webcast on trends in technical communication with special guest Char James-Tanny
February 15: Webcast on HTML5 with guest presenter Peter Lubbers
Week of February 22: Simon Bate presents at tcworld India; Sarah O’Keefe presents at Intelligent Content

Review the entire events list

News from Tedopres

We are doing a few webinars in the next few weeks.

Join our FREE webinar on Simplified Technical English
Clear & consistent content can help you save cost & improve your customer experience

Tuesday, January 31, 2012
4:00 PM – 5:00 PM EST

Visit Tedopres.com or register at https://www3.gotomeeting.com/register/510570974.

Join us for a Free Webinar to learn about STE Tools
Reaping the benefits from your Simplified Technical English implementation.

Tuesday, February 21, 2012
4:00 – 5:00 PM EST

Visit Tedopres.com or register at https://www3.gotomeeting.com/register/604631086

Provide your end user with the right information at the right time.
How you can use Augmented Reality and make your product information interactively available on an iPad. Read more at http://tedopres.com/HyperSIS-Service-Information-System.

News from Adobe

Switch from MadCap Flare, Author-it, or Doc-To-Help Enterprise, or Doc-To-Help for Word and save 40% off Adobe RoboHelp 9!

Struggling with you current Help Authoring Tool? Looking to “switch” to a tried-and-tested tool that has been the professional standard in the user assistance space for the last 20 years? Adobe has the answer … and the perfect reasons too!

Adobe celebrates the 20th anniversary of RoboHelp with a limited period 40% off “switcher” promotion. Switch from MadCap Flare, Author-it, or Doc-To-Help Enterprise or Doc-To-Help for Word and save 40% off Adobe RoboHelp 9!

Time frame: October 17th 2011 through February 16th 2012
Scope: US only

For more details (top reasons to switch, testimonials, switching resources) about the RoboHelp 40% off “switcher” promotion, see the following:

Saibal Bhattacharjee
Product Marketing Manager
Adobe Systems Inc.,
saibal@adobe.com

Tom Deem
Business Development Manager
Adobe Systems Inc.,
tdeem@adobe.com

Blog Sponsors

STC Certification: An In-Depth Interview with Steve Jong

Tom Johnson — Fri, 27 Jan 2012 04:11:47 +0000

The following is a guest post by Steve Jong, chair of the STC Certification Commission.

What does the certification program involve?

First, for an introduction to the subject, I recommend the Wikipedia article at http://en.wikipedia.org/wiki/Professional_certification. Our Certified Professional Technical Communicator™ (CPTC) credential provides assurance to employers and the public that the certified practitioner possesses the knowledge, skill, and ability expected of a competent technical communicator to meet the demands of technical communication projects, today and tomorrow.

To become certified, a candidate must submit a packet of material covering five areas of practice: (1) user, task, and experience analysis; (2) information design; (3) process management; (4) information development; and (5) information production. The packet is given a double-blind assessment by a team of evaluators according to objective criteria. If the packet meets or exceeds the criteria, the applicant is certified.

Once achieved, certification is good for three years; to maintain it, certified practitioners must continue their professional development, through continued learning, attending programs and conferences, or other professional activity—the choice is theirs.

What led to the development of a certification program?

It’s been a long and winding road. The first recorded discussion of certification was an STC Annual Conference all the way back in 1964! STC formed an ad hoc certification group in 1975. Certification languished as a chicken-and-egg problem: members wanted proven value before embracing it, but without a program there was no proven value. Repeated member surveys showed majority support for the concept, though always with a vocal minority in opposition.

In 1985 the committee reached the point of presenting a proposal to the STC Board to undertake a one-time certification of members. Extrapolating from another poll, the plan would have exactly broken even. Given what they felt was a lack of consensus, the Board decided to postpone a decision for two years, which in the end turned into more than 20. During that time certification became much more common among other professions, with plenty of successful examples.

Five years ago, STC commissioned a study that told us we needed three things to be considered a profession: a code of ethics, a body of knowledge, and certification. Independently, we saw that certification is a key characteristic of thriving associations. We already had a code of ethics; we began the BOK work, and certification took on new urgency.

The incarnation of the certification task force that I chaired was able to define overarching areas of practice that are unique to our profession yet shared among our many subgroups. We also came to realize that the certification market was much more than STC members; that certification was not a one-time event but an ongoing operation; and that STC would benefit not just from application fees but also from recertification and training. From this three-dimensional perspective, the economics of certification made sense, and in April 2010 we wrote a proposal that the Board could accept.

Has anyone completed the certification program yet?

We are collecting packets right now. When we have enough we will calibrate the scoring system. We expect to announce the first group of certified technical communicators at the STC Summit in Chicago.

What are the goals of certification?

At the 2009 STC Summit, a group of STC thought leaders brainstormed a list of drivers, or reasons for certification. The STC Board subsequently accepted the list as fitting STC’s strategic goals. This is what the certification program is trying to achieve:

Legitimize the contributions of, and respect for, our profession
Establish uniform worldwide performance standards
Increase the employability and salary of certified practitioners
Satisfy employers’ expectations
Reduce hiring risk for employers
Generate non-dues revenue for the Society

What kind of resistance have you experienced in starting the certification program?

I’ve been presenting the program to audiences for several years now, and a few common themes have emerged. Some people question whether any meaningful assessment can encompass the diverse specialties within our profession. Some people cite a poor doctor, teacher, or plumber they once encountered as proof that all certifications are meaningless. Some people think there’s no need for them to get certified because they personally either have a strong portfolio (when job-hunting) or conduct interviews well (when hiring). Some people say they cannot show their work because everything they do is internal, proprietary, or secret. And some people think the program is just plain too expensive.

How do you respond to some of the objections people have made to certification?

Like other professions that offer certification, technical communication is a broad field. But we are not certifying expertise in subject matter, which employers may determine themselves, or specific tools, which vendors may certify. That narrows things down considerably. What we are assessing is competency in the unique skills we offer, and at that level technical communicators share a core set of knowledge, skills, and abilities regardless of job roles.

We can all think of someone who couldn’t do the job. Ours is not going to be a perfect system, and I’m sure that on occasion someone less than competent is going to slip past us. But that’s no reason to abandon certification. Despite individual examples of incompetents with credentials, no one in the real world seeks out an uncertified doctor, teacher, or plumber. In actuality, that’s the first thing we ask for!

Certification will not replace a strong portfolio or a skillful interviewer. But when we apply for a job, our résumé is only one of dozens skimmed by a recruiter or HR person. In the moment of consideration it gets, certification makes it stand out, which can give you the opportunity to show that portfolio. And at the other end of the process, when a hiring manager has to choose between equally qualified candidates, certification can be the tiebreaker. Our certification is an independent, objective, third-party assurance, and in time it will become a meaningful distinction.

Evaluators must sign blanket non-disclosure agreements, drawn up by our legal counsel, to protect applicant submissions. However, we set up the process so that you can become certified without ever showing a piece of real work. You can use older work, redacted samples, recreations, even simulations. Of course, it’s easiest to use samples drawn from your own portfolio, but you don’t have to.

Finally, certification is an individual decision, and there is no guarantee you that if you get certified your salary will increase or you’ll get a promotion. But in the professions we’ve studied, the average certified practitioner enjoys a salary premium that far exceeds the cost of certification. Compared to certification programs for comparable professions, the cost to obtain and maintain CPTC certification is midrange or slightly lower. So I dare say it’s a bargain!

Who is the target audience for certification?

The CPTC credential is available worldwide to experienced technical communicators who work in English and wish to demonstrate that they have the ability to meet the North American standards for practice. That’s a mouthful, so let me unpack it a bit. We require a combination of experience and education to qualify. While a bachelor’s degree is plenty, if you have five years of experience you really only need a high-school diploma or its global equivalent. (This is how PMI certification works as well, by the way.) With a specialized degree (such as technical communication), the experience requirement is reduced to as little as three years.

You don’t need to be an STC member to get certified, and you won’t need to get certified to be an STC member. Our evaluators work in English; in future we hope to expand to other languages. The mix of knowledge, skills, and abilities we’re looking for were qualified for the North American market, though we’re working to qualify the mix outside North America.

Is the BoK comprehensive enough to be the foundation for a certification program?

Yes and no. To quote its charter, the Body of Knowledge is “attempting to organize, make accessible, and connect together the plethora of information necessary to train for and practice within the profession.” That certainly fills the bill! But the BOK will take time to flesh out. And the BOK team is cataloging material as it arrives, not concentrating on the subset of information we’re certifying. For now we are evaluating submission packets prepared by candidates, which better fits the portfolio model familiar to practitioners. When the BOK is ready we will switch to exam questions drawn from it. So if you’re nervous about taking tests, I suggest you get certified now.

How much does certification cost?

For charter applicants (until 14 February 2012), the application fee is $99, the assessment fee is $495, and the yearly maintenance fee is $49. Additionally, if you return your submission packet by 14 February 2012, we will rebate $100 of the evaluation fee. After that, prices will increase, more so for non STC members. So if cost is a concern, or you’re not an STC member, consider applying now.

What would be the advantage for established professionals to go through certification?

As I mentioned before, certification is a tiebreaker both for setting an interview and for getting an offer. I’m not blowing smoke here: this is what we’ve heard from HR professionals and hiring managers. In uncertain times, certification program applications go up. That’s because people look for every edge they can get.

For a gray-haired veteran, certification won’t make as much difference as it will for a mid-career professionals. But as the Wikipedia article puts it, professional certification stands above your résumé (which is you writing subjectively about yourself) or a reference (which is someone speaking to your role in one place) as an independent, objective, third-party assurance of your competence.

There’s something else to consider. Take my personal example: I was named an STC Associate Fellow this year, and—how shall I put it?—I’m most of the way through my working life. I am not in the target demographic for certification. But I am at the point where I think in terms what is good not just for me but for STC, the profession, and my colleagues. Certification will transform the Society, the profession, and the careers of people working today. To me, anything I can do to help accelerate the growth of the program is worthwhile.

Is there a way to participate as a trainer in any of the certification courses?

Yes! In other professions, the typical certification applicant spends more for training than for the certification process itself. By starting CPTC certification we are establishing a market for certification courses. STC plans to participate in that market, but it won’t be exclusive. Anyone can offer training in the areas of practice.

Steve Jong is a life-long technical communicator, an Associate Fellow of the Society for Technical Communication, a former STC Director at Large, and a former president of the STC Boston Chapter. He is the chairman of the STC Certification Commission, which has been established to oversee the STC certification program. You can read more about certification here. You can follow Steve Jong’s blog here.

Blog Sponsors

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

Upcoming Webinar: Designing Quick Reference Guides

Tom Johnson — Mon, 23 Jan 2012 15:31:14 +0000

I’m giving an STC webinar this week on designing quick reference guides. Here are the details:

Designing Quick Reference Guides
Date: Wednesday, 25 January | 1:00–2:00 PM EST (GMT-5)

Condensing a manual into an attractive quick reference guide requires a poet’s precision with language, but it also requires you to exercise skill with visual design and page layout. These short guides blend marketing with instruction, allowing you to combine text with images to pull readers into the content. Long manuals are outdated, ineffective ways to teach people software.

The quick reference guide (usually 2 to 6 pages), with strong visuals and a magazine-like layout, is something that end-users, project managers, and just about everyone absolutely loves. Quick reference guides should be a standard deliverable that technical communicators emphasize and prioritize in their work.

By the way, if you can’t make the webinar but you’re still interested in the topic of quick reference guides, see this page of quick reference guide resources on my blog.

Graduate Research Findings about Technical Communication and Blogs in the Workplace

Tom Johnson — Sun, 22 Jan 2012 19:07:30 +0000

The following is a guest post by Michelle Tompkins. Earlier this year she asked me to post a survey about technical communication and blogging. I posted it here, and then asked if she would follow up to share her findings. This guest post shares her findings.

Earlier in December, Tom Johnson was nice enough to help me with my graduate research on how blogs are used with the workplace of a technical communicator. I received great feedback from all of the respondents on my survey, and I would like to thank everyone who participated.

Not only did my study look at blog use, but also how social media tools are changing the nature of work for technical communicators. As social media continues to change the way we write and communicate with audiences, it is important to understand the functions, uses, and impacts of these technologies on our work as technical communicators. My short survey helped determine if and how blogs are being used as a professional tool within our field.

After collecting and analyzing the data from my survey, I found that approximately 88 percent of respondents use social media tools at work. When respondents were asked specifically about the type of social media tools used, wikis, social networking sites, and micro-blogging technologies such as Twitter were the most popular.

However, only 69 percent reported using blogs as part of their work. The most common uses of blogs within the workplace were sharing internal company news, communicating with external stakeholders, reviewing products and services, and knowledge management and sharing.

Another common use of blogs by technical communicators was professional development. Many respondents reported blogs as a replacement for the company newsletter, which has created a more dynamic forum for internal information dissemination.

While the focus of my research was specifically on the use of blogs, I was also interested in learning more about how social media tools have affected the nature of our daily work. Surprisingly, only 55 percent of respondents felt that social media tools have had a significant impact their daily work.

Some technical communicators felt that social media tools have opened a new channel of communication, which allows instant feedback from internal and external stakeholders. Another impact of social media tools reported was a more efficient way to store, organize, and share information.

Through my survey and other research endeavors, I believe the most significant impact of social media tools on our field as a whole has been the ability to have a direct connection or conversation with our users, customers, and document audiences. This direct connection with the end user will enable technical communicators to develop deliverables that are more accessible and usable for their specificied audiences.

With all of this said, I believe that social media tools have had a significant impact on the field of technical communication. However, I do not believe that it is inevitable that all technical communicators will embrace these technologies. Not all of technical communication jobs will change, but as evident from my research, a large portion of job descriptions may change as a result of the daily emergence of new technologies.

The most important aspect that I have taken from my research is that blogs and social media cannot be ignored. Even if technical communicators are not using the tools themselves, their users, audiences, and customers are, which forces us as technical communicators to at least be cognizant of these new tools of communication.

Once again, thank you to all who participated in my survey. If you have any further questions about my research, you can reach me at MET7189@gmail.com.

Michelle is a graduate student studying technical communication at the University of North Carolina at Wilmington. You can follow her blog at http://mshelltompkins.wordpress.com.

Blog Sponsors

Using JIRA to Track Writing Assignments

Tom Johnson — Wed, 18 Jan 2012 14:57:28 +0000

We had a couple of writing interns join our group this month. To track writing assignments for the technology blog, I’ve been using JIRA. JIRA is a bug tracking tool from Atlassian (the same company that makes Confluence). It’s typically used by software teams to track bugs during software development projects. You can add comments to items, assign items to team members, assign the items to sprints, create advanced viewing filters for the items, and more.

Since I’m using JIRA to track writing assignments, I have to live with a few compromises in terminology, but so far I like the system. Here are some details of how I’m using it.

Each item in JIRA is an article. I add only articles that we’re really going to write. (For general ideas that may one day be something we write, I put the ideas elsewhere.)

I assign the JIRA items to the writers who will write the article. If there is no writer, I leave the article unassigned.

I give each article a story point weight of about 10 points. Another section of JIRA allows me to define specific sprint release windows, and I organize sprints (based on weeks) to accept no more than 70 story points. This means that each sprint can only have 7 articles, assuming each article is 10 story points. However, I can also adjust the story points for each article. For example, short articles might be 3 story points, while longer articles might be 15 story points. Adjusting for the appropriate number of story points helps us avoid over-allocating work for the week.

In the JIRA item, I try to outline the general ideas the article should cover. I also add comments about each item, and the assignee receives an email notification with each comment and edit.

When an article is completely finished and published, I change its status to Resolved. Or if we decide to not do the article, I resolve or delete the article. The resolution statuses include Fixed, Will Not Fix, Duplicate, and some others.

I can assign different priorities to the articles — 1, 2, 3, 4, or 5. A priority 1 is called a “blocker.” Priority 2 is called “critical.” Priority 3 is “major,” and so on. (Here’s where the terminology doesn’t quite fit for writing assignments.)

JIRA’s filters are robust, but I am using them in a simple manner. I create a filter to show all items assigned to each intern, and then I save those filters as bookmarks. When I review and plan articles with the writers, we just select the JIRA filter and go down the list of what they’re working on.

I’ve tried various ways to organize and track writing assignments, and so far this one seems to work well. Of course no system works if you don’t actually use the system, and no system is perfect. I used to have little slips of paper pinned all around my cube. I’ve also tried Excel spreadsheets, as well as SharePoint.

But using JIRA to track writing assignments is particularly beneficial because familiarity with JIRA helps out with our involvement in project teams. In our IT department, many project teams use JIRA, and familiarity with JIRA makes it much easier to stay abreast of project news, releases, bugs, issues, and other details. Often the lifeblood of a software project is captured in JIRA, since this asynchronous sharing of information helps everyone on the team remain aware of what’s going on.

One thing I’m not using JIRA for is to manage the actual documents. While I could upload file attachments, I find that Dropbox is much easier. Dropbox is almost like a net file share drive. I could spend an entirely separate post describing how much I love Dropbox, but so that I stay on track, I’ll just say that I try to name the Dropbox folders the same as the JIRA item titles.

One other shortcoming of JIRA is that it doesn’t allow me to change the statuses of items in a customizable way (at least I haven’t figure out how to do it yet). I’d like to indicate various states of the article as they pass through the approval processes, but alas, the issues in JIRA are either Open, In Progress, or Resolved. (Perhaps it’s best to keep it simple.)

I’d be interested to hear what system you use to manage and track writing assignments.

Blog Sponsors

A Lifetime of Reading Versus a Lifetime of Writing

Tom Johnson — Fri, 13 Jan 2012 15:46:31 +0000

This past week I traveled to Florida to help clear out my dad’s house. He recently fell and hit his head, and now he’s in a rehabilitation center while his memory recovers. It may take him months to return to his normal self. When he does, we want him to live closer to my sister in Tampa.

I spent an entire day clearing out his office. I boxed up about 15 boxes of books, which will be donated to Salvation Army. While sorting through his library, I found about five genres of books. They could roughly be classified into five piles: literary fiction, poetry, religion, dieting, and gardening. You can tell a lot about a person by looking at what he or she reads. I had no idea my dad’s interest in religion was so pervasive. I boxed up about 14 different bibles. He’s Russian Orthodox, so there was a lot of liturgical books, prayer books, and commentary about early Christian fathers, biblical commentaries, books on transformational christianity, and so on.

The other genres were not insignificant either. Poetry alone probably comprised three boxes — Wallace Stevens, Byron Scott, William Wordsworth, William Carlos Williams, Alexander Pope, and many more well-known poets. In his living room, he dedicated an entire bookshelf for Anne Dillard’s works.

Many books had bookmarks placed about 40 pages into the book, probably where he lost interest. Not every book is worth reading cover to cover.

While boxing, I set aside some books for myself, such as What the Dog Saw, a new book by Malcolm Gladwell, The Origin of Creativity (it looked interesting), John Muir’s Longest Walk, and Things I Learned About My Father in Therapy, an anthology by Heather Armstrong.

Looking at all the books in the library, I am not sure that reading deserves so much praise. Certainly, much of what we write is a response to what we read, coupled with our experiences. We need some level of information to write. But if reading is merely absorbing information, soaking it up like a sponge, at some point, reading becomes passive. The reader must do something with the information: contemplate, act, experiment, reflect, respond, try, hypothesize, write, and so on. Reading is a catalyst for action (unless it’s just a leisure activity, or something to do to fall asleep).

About six months ago, my father was up visiting me in Utah. During his stay, he was pouring through The Happiness Project, by Gretchin Ruben, and taking copious notes. Presumably, he was reading to discover ways to be happier. He wasn’t just soaking it in. He was reading to act.

In his youth, my father was an English graduate student at the University of Washington, and he planned to move to Australia and write the great American novel. But then he realized, through reading, that the great American novel had already been written, time and again. The realization took away his motivation to write.

He’s actually an excellent writer, so far as I can tell from his letters. My mother said he would often compose essays for his classes just once, with little or no edits, and get As. She was disappointed that he did not finish his PhD and become an English professor.

The market for English PhDs was just as bad in the 70s as it is today, so it’s no wonder my father pursued a different route. Instead of going the PhD route, though, he made a terrible choice: He bought a tavern, and drank himself into alcoholism. Alcoholism sort of derailed his life. He later joined AA and became sober — and has been for 30 years — but he feels alcohol was the cause of so many of his life’s problems.

While boxing up books, cleaning up notes and endless office papers, I kept wondering, why not write more? So what if the great American novel has already been written. Does that make it a vain, repetitive effort to write it again? Exactly how much time should you spend reading? Isn’t there personal value in writing, even if the writing is redundant to other writings?

My personal approach is to read moderately. I wish I were a more voracious reader, but ultimately my real goal is to write a page, or post, since I’m a blogger. I keep stacking up my posts on findability, one after the other. When I hit 100, I figure I’ll have explored the topic deeply enough to begin writing and organizing a book. All my research will be there, ready.

Reading is certainly a catalyst for thought. When I draw a blank for topics to write about, I just search twitter for #techcomm, and review the most interesting post I find. But I always want to move into the writing space, rather than just reading. When I write, it forces me to evaluate topics more rigorously. It requires me to think about what I think. It gives me space to explore, and allows me to dabble in the world of ideas.

I loaded about fifteen boxes of books into my dad’s old yellow pickup and drove several miles to the nearest Salvation Army. Though I donated the books, I did save all papers — journal entries, notes, binders, anything I could find that was a personal expression he had written. I guess books themselves, the ones you choose to keep and line your bookshelves with, are a personal expression that reflects your interests and life’s passions. But somehow they didn’t seem worth keeping.

Blog Sponsors

The “Home Depot Model” of Findability, or, Social Search

Tom Johnson — Tue, 10 Jan 2012 15:12:37 +0000

I walked into Home Depot the other day and, seeing a clerk near the entry way, asked where the storage boxes were. Immediately the clerk told me. After I found my boxes, I asked another clerk where the gloves and Sharpee markers were. Again, she gave the answer immediately. In my experience, apart from wandering aimlessly around the store for extended periods of time, this is about the only way to find things in Home Depot.

In the goal to find something, I relied on the social assets around me. In Greg Nudelman’s Designing Search, he talks about how people are increasingly turning to their social networks for information. Not only do social networks provide quick answers, but finding through social means allows you to draw upon people with similar interests.

For example, I have a large network of technical communicators that I follow on Twitter. If I have a question related to tech comm, it makes sense to ask my tech comm network. Most likely they could give better advice then simply searching the general web or turning to a friend on the basketball court.

Anne Gentle has written about social search on her blog Just Write Click. She notes that there’s an increasing trend to turn to your social network for answers rather than the help documentation. She explains,

Lastly, counts on click-throughs on Google searches may soon be surpassed by counts on click-throughs on social sites. Think about this for a moment. … you are more likely to get useful links by asking your friends and colleagues about certain topics than you are going to get them by searching on Google. This finding is a serious disruption for the web, if it turns out to be true. I haven’t seen studies yet that have numbers to support this claim, but I’ve seen it in slide decks about social support communities, community management, and the like. (See The Big Shift From Search to Social)

In other words, people may be searching on social sites like Facebook more than they search on Google because they get more useful information from social sites. As for metrics to support this, I recently saw this 60 seconds graphic:

Infographic by- Shanghai Web Designers

Unfortunately the original post doesn’t cite references, but if it’s true, in one minute there are 694,445 search queries on Google, while there are 695,000 Facebook status updates and 510,000 Facebook comments, along with 98,000 tweets on Twitter. If even ten percent of these social posts and comments are questions and answers, that’s a huge number of people using social networks as a means of finding and sharing information. It’s not a source to be ignored in the effort to make your content findable.

One challenge with increasing your influence in social search, of course, is bandwidth. It’s not possible to connect with so many people, right? One has only so much time to respond to forum posts, comments, and other social threads. Maybe not.

In a recent internal conference, one presenter explained how to get customers to adopt new products you’re rolling out. The presenter encouraged development teams to connect with key influencers in the community. If you can get the key influencers on board, they can help others, the presenter explained. Every department has that one person whom everyone goes to for help. If you give these influencers access to beta test software, reach out to them personally, and reward them for their helpfulness, they can be a huge asset in social findability.

In The Tipping Point, Malcolm Gladwell calls attention to several key types of people that can cause products to tip. Mavens and connectors (the terms he uses) can be key touchpoints for increasing awareness. When I walked into Home Depot and found a clerk, she immediately routed me in the direction I wanted to go. Although there were probably 50 people in the store, and only about 5 clerks, if I wanted to share information with all the people in the store, I’d focus just on the clerks.

The following graphic shows this workflow. As a technical writer, you don’t need to interact with the social web in its entirety. You just need to interact with the influencers (the mavens and connectors). These influencers are the forum champions who regularly interact with scores of people and thrive on helping and guiding others. They may be the administrative assistant in a department of executives, or perhaps prolific bloggers. The influencers will then interact with the rest of the user base.

If you focus on mavens and connectors (the key influencers), the rest of your end-users will get the information as they reach out to them.

In contrast, if you interact with users on a one-to-one basis, you’ll be overwhelmed with individual support requests and time-draining questions. I know that in past experiences, I’ve reached out to some users to gather their feedback. Later, I became their personal support assistant at beck and call whenever they had a question or problem. That kind of relationship can be very time-consuming.

If you do have the bandwidth to embed yourself in social sites and interact on a one-to-one basis, at least transfer the information you provide into the help content (assuming it’s not already there). This way you’ll convert the one-to-one interaction into a one-to-many interaction and allow influencers to get the information they need to help others.