May 132017
 

Icon of handshake, with circular arrows symbolizing an even exchange[Ed. note: This is another in a series of occasional articles by Jack Molisani. Here Jack expands on ideas he presented at our April 2017 program.]

For many people the term “negotiating” brings to mind images of unpleasant haggling with a used car salesperson in a loud plaid suit. But negotiating isn’t something you do just when buying a large-ticket item like a washing machine or a used car. Deciding what features will be documented given the time on hand, getting your kids to clean their rooms before playing video games, even deciding what movie to watch on Date Night, are all negotiations in one form or another.

What is Negotiation?

Webster’s Dictionary defines negotiating as “conferring, discussing, or bargaining to reach agreement.” Dictionary.com defines negotiating as “to attempt to come to an agreement on something through discussion and compromise.”

I find these definitions lacking—they just don’t capture the true spirit and goal of negotiation. So after reviewing my 25+ years experience as a negotiator (first as a Systems Acquisition Officer in the Space Division of USAF, then as a staff and contract technical writer, and finally as the owner of my own business), I created a better definition:

Negotiation is the art of giving up as little of what you have in order to get what you want.

What would you as a staff or contract technical communicator be negotiating?

  • Your compensation
  • Project scope
  • Project deadlines
  • Resources
  • Headcount
  • Comp time
  • Training
  • Tools, etc.

What do you regularly give up to get what you want in the workplace?

Negotiation Basics

One negotiates to reach a common agreement. I believe all negotiations have to be either Win-Win or Lose-Lose to be considered “successful.” For example:

A sale: Buyers gets a product (or service) they wanted at a price they can afford, and the seller make a reasonable profit

A war: Both factions split the territory in dispute. Neither side is happy, but it’s certainly better than fighting

Win-Lose is not “negotiating.” When one side forces their terms on the other, there is no common agreement, no meeting in the middle. The other party may accept the offer because they have to, but they sure aren’t going to like it, and they certainly are not going to give 100% if they feel cheated.

What do you think a vendor will do who sold their service for less than what they consider a fair price?

What do you think customers will do if forced to pay more for something than they feel they should have?

What do you think employees will do if they accept a salary that is much lower than what they think is fair?

Let’s look at some lessons learned and best practices for conducting negotiations.

Before You Begin

The first thing to do before starting any negotiation is your homework. Decide before you begin what you would like to achieve. Decide what is a nice-to-have, what is a must-have, and at what point will you walk away from the negotiations if you are just not getting what you want.

Don’t try to decide these things during the negotiation. There is usually far too much stress or emotion in a negotiation, and you don’t want to make a snap decision that you will later regret.  

Also, Chellie Campbell, author of Zero to Zillionaire, talks about doing business with “Your People.” You recognize Your People when you meet them. They value your services and are happy to pay your rates for a quality product or service. They want to strike a deal that is good for both parties.

So the next step after doing your homework is to find Your People and negotiate with them.

At the Start

When opening a negotiation, don’t just jump into price negotiations. Take time to get to know something about the person with whom you are negotiating, and for them to get to know you. They will be more open to negotiating if they feel you are “birds of a feather,” so look for shared values and common ground.

Also find out what is important to them, and let them know what is important to you. (More on this later in the article.)

Opening Offers: Theirs

When possible, let the other side make the opening offer. That is the first insight you get into what they have in mind as a fair price, and you can decide if the deal is even worth pursuing.

When a company comes to me looking for a contract technical writer, I usually ask: “Compensations can vary widely based on the amount of education and experience they have. Do you have a particular range in mind so I don’t send anyone too expensive…?”

If a client tells me they want someone for a ridiculously low amount, I assume they’re telling me the truth—they really are looking for a writer for $x/hour. In that case I don’t even try to negotiate. I just say, “Sorry, there is no way I can find someone at that rate and still include a margin to cover my overhead.”

But if the number is not too far from your target, you can ask to split the difference, or even just agree to their number if it is not too far from your own.

Opening Offers: Yours

There will be times when you will have to make the opening offer, such as stating your bill rate or salary expectations in an interview. I have a rule of thumb: The better the interview went, the higher the number I quote when they ask my bill rate.

However, I always add a qualifier in case I needed to backpedal. I say, “My normal bill rate is $x/hr…” and then watch their reaction.

If they accept my rate without hesitation, I make a mental note to raise my rates!

But if they react negatively, I can quickly add, “…but I’m flexible given that this is a long-term contract [given the state of the economy, etc.].”

But—if they react negatively and I have to backpedal, I also add, “What bill rate did you have in mind…?”

Justifying Your Numbers

For bidding projects (no matter if you are an internal employee or an external contractor), you must be able to show how you came up with your estimate.

The best way is to support your numbers with historical data. “The last time we did a project just like this it took….” If you can show exactly how you came up with your numbers, the negotiation will swing away from your hourly rate and onto the scope of the project.

For more information on how to justify numbers in a workplace negotiation, see “How to Build a business Case,” Molisani/Graham, Intercom, July/Aug 2008.

For more information on how to track historical data, download the session slides and a sample database from Bonni Graham’s presentation, “How to Create a Historical Database and Bid Future Jobs” from LavaCon 2006.

Negotiating: Give and Take

Remember, most people consider making and receiving concessions as part of the negotiation process. So knowing the other person expects me to give up something as part of the negotiation, I always add things to my “wish list” that I am willing to negotiate away.

At the start of the negotiation I ask the other party what is important to them. That way I can say if you give me what is important to me, I’ll do what I can to give you what is important to you.

When I do that, I find negotiating a deal is much closer to a dance than a tug-of-war.

Summary

To recap:

  • Negotiation is the art of giving up as little of what you have in order to get what you want
  • Find and negotiate with Your People
  • Take time to build rapport with the other party
  • Decide before you start what you want, what you are willing to give up, and when to walk away
  • When possible, let the other party make the opening offer
  • Be able to back up your numbers and estimates
  • Go for a Win-Win agreement

About the Author

Headshot of Jack MolisaniTwitter

Jack Molisani

Jack Molisani is the president of ProSpring Technical Staffing, an employment agency specializing in technical writers and other content professionals, and is the author of Be The Captain of Your Career: A New Approach to Career Planning and Advancement, which hit #5 on Amazon’s Career and Resume Best Seller list.

Jack also produces the LavaCon Conference on Technical Communication Management: https://lavacon.org.

Jack is always happy to hear from readers, so if you have any questions or success stories to share, contact him at Jack@ProspringStaffing.com.

Follow Jack on Twitter.

Jun 202016
 

[Ed. Note: This is the Third of a three-part article on the impact of mobile on technical communication.]

How Mobile Will Change Technical Communication, Part Three

By Neil Perlin

What to Start Thinking About

In this section, I’ll discuss technologies that exist but have little presence in technical communication to date. That situation could be because there’s just no fit, but it could be because the fit hasn’t happened yet. (HTML and technical communication were in completely separate silos until Microsoft unexpectedly merged them in 1997 with its release of HTML Help.) So keep an eye on the technologies discussed here.

“True” Apps for Technical Communication

Responsive design lets us create material that can be read on mobile devices but that material doesn’t look like typical apps. The example on the left is from a responsive output that I created using Flare 11. It looks rough because I simply output an existing project without optimizing it for responsive output, but it is running on a mobile device. The center example is a preliminary app that I did for the New England STC’s Interchange conference in 2015. It looks rough because it was a functional prototype, but it illustrates visual capabilities that responsive output won’t have without additional work. The example on the right is a completed diabetes monitoring app.

Technical communication and apps aren’t the same thing, you say? Perhaps, but there’s no reason why our content can’t be as visual and word-light as an app while adding an app’s responsiveness, location-awareness, and other features.

RO_Flare11RO_interchange2015 RO_monitoring app
The functionality differs from what we’re used to in tools like Flare but the interface will quickly become familiar.Technical communicators with whom I discuss app rarely think of themselves as app developers because of differences in the technologies and the tools. But here’s the main interface for ViziApps, the tool used to create the two apps above (and, in the interest of disclosure, a tool in which I’m a certified consultant and trainer).

ViziApps

 

If traditional documentation isn’t enough and you need interactivity, more of a visual element, location-sensitivity, and similar features, you may find yourself creating apps in the near future. You’ll be buying and learning new tools and concepts. You’ll also be revisiting issues like what email client users have on their phones (which sounds new but is actually similar to the old issue of what browser users had, if any, on their PCs in the mid-1990s). And you’ll be facing truly new issues like putting help content (data) into a database in order to pass it to or share it with an app.

We’re going to have to think differently about our content in order to make it work with apps and take advantage of the capabilities they offer.

New Interfaces

Keyboards and screens have been the main interface for years and work fine, but not for mobile where users may not have the space for them. (Although technology may be changing the screen issue; see this video  for an idea what new glass technology may do to displays in the years ahead.)

The likely replacement seems to be voice interfaces like Apple’s Siri and Amazon Echo’s voice interface. Another interesting idea is Google Now On Tap’s intelligent assistant and the ability to get help about what’s on an app screen without leaving the app.

voice_interface_siri

Working in this environment means writing content to be spoken instead of read, or both. We may also have to get involved in the technical side of audio, such as the CSS standard’s audio properties like pitch and pause-before. I haven’t heard of any technical communication projects voice as an interface yet but the technology is out there waiting. (If you are using voice for the interface on an online help project, please contact me.)

Adaptive Content

One looming problem with creating content to be used on multiple platforms or in multiple scenarios is content adaptation. Consider the “click” vs. “tap” issue when content may be used on both desktops and mobile devices, such as for responsive design. How do we deal with this? (You’ll find a discussion of this issue on LinkedIn here

One answer is to use intermediate words like “select”, but this can be ambiguous or just sound clunky if users have to select an item from a list and then “select OK”. An alternative is to create computer-driven adaptive content that uses CSS and media queries to test for the device display size and change the text accordingly. Mike Hamilton from MadCap Software and I created a prototype of this for Flare in 2014. The code isn’t pretty but it’s worked nicely in every test I’ve run. (Email me if you’d like to see the code.)

Note that this use of CSS also ties back to my earlier point about becoming more technical.

Content Customization

Content customization has been with us for years on the web as user preferences are tracked by various types of analytics software. You see it every time Amazon presents you with a list of options based on your previous purchase decisions. That tracked information can be thought of as a “data halo” (a Cognizant term) around users. Most of it today applies to ecommerce, but it may apply to technical communication as well.

For example, if certain users access the same help page or search on the same subject daily, analytics can keep track of that and let you offer that page or search result automatically when conditions are the same as on previous occasions.

You can collect the analytic data to do this using a general technology like Google Analytics or, more specifically if you’re a Flare shop, MadCap’s Pulse add-on.

However you do it, it’s a good idea to start collecting analytic data now. If you want to start creating customized content in the future, you’ll be building the data foundation now. And even if you don’t think customization is in your future, the collected search data will still give you information about what users are looking for and can and cannot find, information that will help you improve the online help and the product to which it refers.

Cross-Device State Preservation

Finally, consider that “mobile experience” users may find themselves starting to read your material on a PC in the office, then go out on the road and want to keep reading the material on a tablet or phone or have it read to them while driving their car. Easy. Just re-open the material and read it again. But what if users want to continue where they left off on the desktop but on a completely different device without having to restart from the top?

I saw the idea mentioned once in 2015 and most recently in a Bright Ideas for 2016 article in the January 2016 issue of Wired. (The idea is so new that it doesn’t even seem to have a name. I just made up the term “cross-device state preservation” in order to have a reference in conversations.) No doc group that I’ve spoken with has gone far enough down the mobile path for this to be an issue, but one lesson from the rise of online help is that things change and that it’s better to do things correctly from the beginning than to have to go back and fix them afterwards.

I’ve spoken with several engineering managers about how cross-device state preservation might work. It will require that the material be stored on a server and dynamically reformatted for whatever device is being used to read it, plus internet access (obviously), plus a login to let the server and format software knows what material to format for which user, plus syntactically correct code, plus extensive use of metadata. All these requirements make cross-device state preservation the most esoteric of all the new mobile experience technologies.

Summary

Some of the effects of mobile on technical communication are obvious – new tool and technology skills, huge changes in how we create content, new problems (and new forms of old problems), plus changing business models and intra-company relationships. But the biggest effect will be the emergence of new and challenging lines of work that I expect can take our field in unexpected directions and bring a younger generation into the field.

Thanks to…

The following people for their direct and indirect contributions to the subject of mobile and tech comm and this article:

  • Rhonda Truitt and Sally Martir, Huawei, organizers of Huawei’s Mobile Info Think Tank
  • Mike Hamilton, MadCap Software, for his work on CSS-based adaptive content
  • Nicky Bleiel and Bernard Aschwanden, STC, presenters with me at Huawei’s Mobile Info Think Tank
  • David Kay, D.B. Kay and Assoc., presenter at Huawei’s Mobile Info Think Tank
  • Kevin Benedict, Cognizant’s Center for the Future of Work, presenter at Huawei’s Mobile Info Think Tank
  • Joe Barkai, Product and Market Strategist and Catalyst, presenter at Huawei’s Mobile Info Think Tank
  • George Adams, CEO, ViziApps
  • Michael Kuperstein, CTO, ViziApps
  • Charles Cooper, Rockley Assoc., presenter at Huawei’s Mobile Info Think Tank
  • Neal, Carol, and Katherine for serving as an impromptu sounding board at the picnic table at TCUK’15

About the Author

Neil is president of Hyper/Word Services (www.hyperword.com) of Tewksbury, MA. He has many years of experience in technical writing, with 31 in training, consulting, and developing for online formats and outputs ranging from WinHelp to mobile apps and tools ranging from RoboHelp and Doc-To-Help to Flare and ViziApps. He has also been working in “mobile” since 1998.

Neil is MadCap-certified in Flare and Mimic, Adobe-certified for RoboHelp, and Viziapps-certified for the ViziApps Studio mobile app development platform. He is an STC Fellow, founded and managed the Bleeding Edge stem at the STC summit, and was a long-time columnist for STC Intercom, IEEE, and various other publications. You can reach him at nperlin@nperlin.cnc.net.

Jun 042016
 

[Ed. Note: This is the second of a two-part list of tips for using the editorial tool Acrolinx.]

Encourage writers to submit issues and suggestions

Due to the complexity of the English language, Acrolinx is going to have false positives. For example, the tool might misread “…the two menus, View and Edit.” as a list of three items and recommend inserting a serial comma after View. In situations like these, it’s critical that writers can submit these issues to the Acrolinx team as easily as possible.

Create an email address for your Acrolinx team and encourage writers to send in their issues and suggestions. Also consider customizing the Acrolinx flag reports so that writers can email the team directly from the reports.

The writers are your ears on the ground, so encourage them to send false positives whenever they encounter them. You can’t improve Acrolinx if you don’t know what’s broken.

Customize the rules to match your style

Screenshot of Acrolinx Scorecard featureAcrolinx GmbH

The Acrolinx Scorecard

Acrolinx ships with a common set of rules that apply to large swaths of documentation. But these rules don’t cover everything. Customization is the key to making Acrolinx work for you. Go through your style guide and add in those clear-cut rules that Acrolinx handles so well, such as ones for hyphenation, capitalization, and bulleted lists.

To further customize Acrolinx, you can apply rules only to certain XML elements. For example, if your style is to write <heading1> elements in Book Title Case but <heading2> elements in Sentence case, Acrolinx can check for that.

You can also turn off rules where the rules of English don’t apply. Suppose you have an element that lists a summary of valid values:

<values>on | off</values>

You can have Acrolinx ignore content found in these tags. This feature works for inline elements as well. Take the sentence “Open the <label>View</label> menu.” You can have Acrolinx skip over the <label> menu so that the tool doesn’t mistakenly misread View as a verb.

Rewrite the Acrolinx help to use your own examples

For each flag you receive, Acrolinx provides the rule associated with the flag, plus a few generic example sentences. For example, here are a few example sentences from the “uncountable noun” rule:

Incorrect: An information is available at the company website.

Correct: Information is available at the company website.

To better meet the needs of your writers, replace these general sentences with relevant, domain-specific ones instead. Writers are more likely to internalize the Acrolinx rules when the examples match what they see in their own documentation.

Explore advanced features

Other Acrolinx features include a terminology checker, which can further enhance consistency and reduce translation costs. You can also use it make more domain-specific word lists that run only on subsets of your documentation. Acrolinx is only as effective as the amount of effort you put into it, so it pays to take advantage of its advanced tools.

About the Author

Headshot of Will Tripp

Will Tripp

Will Tripp is a technical editor at MathWorks in Natick, MA. Will has a BA in English from the University of New Hampshire, an MA in Writing and Publishing from Emerson College, and a certificate in Technical Writing from Middlesex Community College. He has more than 15 years of professional writing and editing experience.

May 122016
 

[Ed. Note: Here at the News we’re suckers for listicles, so we’re pleased to bring you the first of a two-part list of tips for using the editorial tool Acrolinx.]

Acrolinx is a language, grammar, and terminology checker that runs as a plugin in most XML editors. You write your content, you choose Acrolinx from the menu, and you get a report of the potential flags associated with the content, such as missing serial commas or use of the passive voice. You can also add your own checks.

Screenshot of sample Acrolinx sidebarAcrolinx GmbH

The Acrolinx sidebar

We started using Acrolinx at my company, MathWorks, about a year ago. While it took time to overcome implementation challenges and get writers to fully integrate the tool into their workflow, we have started to see positive results. Writing quality and consistency have gone up, new writers are internalizing our company styles more quickly, and overall, writers and editors have more time to focus on substantive content issues.

If you’re considering using Acrolinx for your company, keep these tips in mind to make sure your implementation goes smoothly.

Don’t make fixes mandatory

When you first implement Acrolinx, let writers know that Acrolinx is designed to help them. They’re not being graded on the number of flags they receive, and they’re not expected to blindly address every flag. Critical thinking about the content still applies. For example, if the tool flags a sentence for using passive voice, but passive voice is appropriate in that case, then the writer should feel confident in ignoring the flag.

Let writers determine how to integrate Acrolinx into their workflow

All writers work a little differently. Some prefer to run Acrolinx only after writing a whole help topic. Others prefer to run Acrolinx after they write one section, or even just a few sentences. As long as writers are running the tool, leave it up to them on how to use it.

The more flexibility you give writers in implementing Acrolinx, the more buy-in you get. The rules that Acrolinx applies are common sense, so writers tend to appreciate rather than resent the flags they receive. Eventually, writers internalize the rules and get fewer flags to begin with.

Understand the limitations of Acrolinx

By learning the strengths and weaknesses of Acrolinx, you gain a better understanding of what the tool can and can’t check for you. For example, Acrolinx can’t tell you when your information is inaccurate or harmful to the user. It checks the syntax of a sentence, not its content. For example, this sentence raises no Acrolinx flags:

To get your toast from the toaster, use a knife or fork.

Also, Acrolinx can’t fix your paragraphs, because it operates at the sentence level. As soon as it reviews one sentence, it forgets it and moves on to the next one. You can have a whole paragraph of Acrolinx approved sentences that don’t add up to a coherent idea.

Have a team in place to address issues

Having a dedicated Acrolinx team in place is essential for a smooth implementation. Good candidates for the team include writers, editors, content strategists, or anyone else who interacts with the tool. The team can troubleshoot issues writers are having, and they can refine or add rules based on suggestions from writers and editors.

When you first implement Acrolinx, the team members also act as advocates for the tool and can help writers see its benefits. After implementation, they can explore new features to further improve the tool.

About the Author

Headshot of Will Tripp

Will Tripp

Will Tripp is a technical editor at MathWorks in Natick, MA. Will has a BA in English from the University of New Hampshire, an MA in Writing and Publishing from Emerson College, and a certificate in Technical Writing from Middlesex Community College. He has more than 15 years of professional writing and editing experience.

Apr 302016
 

[Ed. Note: This is the first of a three-part article on the impact of mobile on technical communication.]

How Mobile Will Change Technical Communication

By Neil Perlin

If you’re fairly new to technical communication, the images below may look unfamiliar but both were turning points in the evolution of the field.

word processor
An early version of Windows Help

Word-processors came on the scene in the early ‘80s and put an end to typewriters, galleys, and other paraphernalia of a lost age, replacing them with tools like Word and Framemaker. Windows Help was Microsoft’s online help standard from 1989 to 1997, starting the shift from print to today’s browser-based outputs.

We’re now looking at the next turning point, mobile. Consider this chart from Gartner IDC:

Digital Device Sales Graph

“Mobile” goes beyond phones, even beyond devices. As Kevin Benedict from Cognizant’s Center for the Future of Work put it, “The age of the mobile app is dead… it’s now the ‘mobile me’ experience.”

As mobile spreads, our readers will expect to get documentation the way they get news or social media. How will those expectations affect technical communication? That’s the subject of this article.

I’ll first briefly discuss the impact of mobile and what we need to do now to fit it into our worldview. I’ll then discuss some technologies that are five to eight years out but that we need to start thinking about today.

This article is based on a presentation that I’ve given at several conferences. That presentation is based on Flare and RoboHelp consulting, app development consulting, and a think tank put on by Huawei in Plano, TX in the fall of 2015 in which I participated. All parties will be acknowledged at the end of this article.

What to Do In the Short Term

In this section, I’ll briefly discuss things we should be doing anyway, mobile or not. The advent of mobile only increases their importance.

Define the Benefit That We Offer

Show that technical communication goes beyond writing manuals. Instead, it supports the company’s business strategy and might even act as a revenue generator (discussed in the next section).

The goal – Make sure the doc groups are active players in the company’s technical and business strategy and thus have the credibility to participate in any mobile effort.

Look at New Business Models for Technical Communication

As long as I’ve been in the field, there’s been debate about how to turn technical communication from a cost center into a profit center, or at least a revenue generator. How might we do this?

One interesting example is Dozuki (www.dozuki.com) and iFixit (www.ifixit.com) that offer post-sale service manuals online and sell tools and parts along with the manuals. Whether or not something like this might work for you, it’s a clever alternative to traditional technical communication.

The goal – Look outside the traditional technical communication business box.

Define What “Mobile” Means for Your Situation

When online help shifted to HTML in the late ‘90s, there was a lot of confusion over terminology. Was “HTML Help” the same as “HTML help”? Was “WebHelp” the same as “Web Help”? Did we have to use WebHelp for material on the web and HTML Help for material to be stored on users’ local PCs? This confusion led to companies buying the wrong authoring tools, hiring the wrong developer, creating the wrong outputs, or all three.

Today, we face the same definition issue with “mobile”. Is it a mobile-optimized web page? Responsive design? An app? Something else? Until you define what “mobile” means in your circumstances, you run the same risk of buying the wrong tools, hiring the wrong person, or developing the wrong output. Defining “mobile” isn’t difficult; it simply has to be done.

The goal – Set a clear direction for moving into mobile to avoid repeating the mistakes of the past.

Code Correctly

Every language and tool has hacks and workarounds that are fun to find and interesting to try, but they can be trouble. The latest version of your browser may not recognize a hack that worked three versions ago. Conversion tools may not recognize your cool hack that worked in an older version of the tool or that was meant to be run by hand. As someone once said, “A hack is a one-off; good coding is forever.”

The goal – “Future-proof” your material to be able to take advantage of new mobile outputs and tools without first having to clean up those hacks that originally seemed so clever.

Become More Technical

Technologies like CSS have great capabilities, such as the ability to create adaptive content, but if you’re not at least conceptually familiar with the technology, you’re limited to the features that your GUI tool supports. Becoming more technically adept opens up those capabilities. For example, learning how to place images using the IMG tag’s float property rather than using tables will allow you to place images that automatically adapt to the size of the display screen.

The goal – Be able to use mobile and related technologies to their fullest extent now rather than having to wait for your GUI authoring tool to catch up.

Part two will continue with more short term practices to consider including the “mobile first” approach and navigation models.

About the Author

Neil is president of Hyper/Word Services (www.hyperword.com) of Tewksbury, MA. He has many years of experience in technical writing, with 31 in training, consulting, and developing for online formats and outputs ranging from WinHelp to mobile apps and tools ranging from RoboHelp and Doc-To-Help to Flare and ViziApps. He has also been working in “mobile” since 1998.

Neil is MadCap-certified in Flare and Mimic, Adobe-certified for RoboHelp, and Viziapps-certified for the ViziApps Studio mobile app development platform. He is an STC Fellow, founded and managed the Bleeding Edge stem at the STC summit, and was a long-time columnist for STC Intercom, IEEE, and various other publications. You can reach him at nperlin@nperlin.cnc.net.

Apr 062016
 

[Ed. Note: This is the second of a two-part article on techcomm in service organizations. Part One is here.]

Part 2 – Challenges Facing Technical Communicators in Service Companies

Last time I told you about the value technical communicators can bring to service companies. Service companies give technical communicators a chance to prove the value of documentation outside the traditional “product documentation” role. But service companies also present challenges. Some challenges stem from the short-term business strategies and fragmented management structure of many modern organizations, while others stem from the habits and expectations that many documentation professionals bring from previous product-orientated roles. Continue reading »

Mar 262016
 

[Ed. Note: We are pleased to offer the first of a two-part article on techcomm in service organizations.]

Part 1—Documentation for Companies with No Products

Technical communicators find themselves in a rapidly changing marketplace. While “technical writer” is still a common job title, many communicators are now tasked with creating instructional videos, information graphics, and Web site content as well as traditional documentation such as manuals and online help. But while our deliverables now include new kinds of content, our goal remains the same—providing users with the information they need to use the product. Continue reading »

Feb 272016
 

I proposed this article at the End of Year celebration last June, after I graduated from the University of Massachusetts Dartmouth with my Master of Arts in Professional Writing. Earlier that month, I accepted the first job offer that came to me, a technical writing/documentation specialist position at Canary Systems, Inc.. Located in New London, New Hampshire, Canary Systems is a small company that creates instruments called dataloggers, which collect data from structures like dams and mines, and they relay the information back to users through a proprietary software suite, MultiLogger®, which manages an entire network of these dataloggers and their data.

I was excited to finally end my job search and I stood ready to take on the world. I moved from Connecticut to New Hampshire in early July and was prepared to begin my job. I walked in, built my own desk, received my laptop, and sat down, eagerly awaiting my first task. I quickly learned that I was going to have quite an ordeal.

My first few months were a trial by fire. Upon arriving, I learned the company had fallen behind on its documentation obligations, and that the documentation duties went to different people, like the company president or the software support engineer. My first task was to update the documentation for the 2014 release of MultiLogger, and I had to ideally have these updates in time for the 2015 release, which was scheduled for the end of August. In addition, I had to acquaint myself with MultiLogger and learn how to use it so I could properly document these features.

This was a tall order, and to compound the challenge, the subject matter experts I needed to talk to worked remotely and could only be in the office once a month at best. My solution was to sit down and learn the software with some of my co-workers, when they had the time to spare. I used what information I had to update the documentation. I was introduced to SnagIt, which I used to capture high-quality screenshots from the software to place in the user’s guides in Microsoft Word. Also, I learned how to create and edit help files in Doc-to-Help 2011. I improved the organization and readability of the user’s guides while I implemented the new information I learned from my own use of the software.

When I handed my first drafts of the user’s guides and help files to the subject-matter experts, they commented where I wrote information incorrectly. I thought I had the right information, from my coworkers and my own observations, but I missed documenting certain features that were not readily apparent. So I tried again until I reached an acceptable level of technical accuracy. Eventually, the user’s guides and help files were updated, albeit a month after the 2015 version was released.

As I began work on the 2015 documents in October, I needed to implement a structure so that they could be completed in a timely fashion. I decided that after I drafted a user’s guide, it would be sent for review of technical accuracy. Then, I would send that updated draft to the marketing director for readability. After I addressed all his comments, I would give a printed copy to the president, who would give a final review. Once he approved of the user’s guide, a PDF version could be put on our website. Because our help files are based on the user’s guide, I would wait until the user’s guide was complete before building the help file.

In addition to my documentation duties, I worked on pet projects to improve the company’s procedures. I created a style guide that would set standards for all software user’s guides. I and my successors would adhere to it and update it as necessary. I used the features in the current documents and incorporated them into the style guide. In addition, thanks to our chapter’s November 2015 program, I piloted a video tutorial workflow, helping fulfill the marketing director’s desire to create a library of videos.

Of the six user’s guides and three help files that accompany a software release, I have completed four of them, as of this writing, with a fifth undergoing revision. I also have completed one of the help files. I am now at the tail end of the 2015 documentation. Our 2016 release is coming up and I will have to change gears to update the documents to account for the new features by the time it launches in the spring.

The biggest challenge for me in this role is to speak up and suggest changes to the documentation workflow. I was skeptical about proposing new ideas to my president early on, as I did not want to rock the boat. Now that I’m six months in, I feel like I have enough experience to pitch new ideas to my president so that I can make a difference at the company.

I want to implement a document management system so that I don’t have to juggle versions of documents that sometimes don’t sync up properly. I want to hold reviewers more accountable to their tasks by checking in with them twice a week, so I can ensure timely feedback. I want to be more hands-on with the subject matter experts, so I can receive the knowledge I need, and they, in return, can see where the software can be improved. I want to set up a testing environment, so I can explore MultiLogger and recommend improvements to the user experience.

Finally, I will acquire more robust tools so that I can work with the information in a more versatile way. They would also improve my productivity and free up time for other tasks—creating video tutorials, updating the application notes, and maybe even updating the hardware documentation. When I attend the Summit in Anaheim, California this year, I will see what’s available and choose the one that fits our needs the best.

About the Author

Photo of Paul Duarte

Paul Duarte

Paul A. Duarte is a Documentation Specialist at Canary Systems in New London, New Hampshire. He holds an MA in Professional Writing from the University of Massachusetts Dartmouth. Paul is Vice President of the New England Chapter.

Feb 062016
 

Consider the last process you conveyed in writing. Was it a complex one? If so it took you some time to convey all the concepts in your prose. And then perhaps more time to fill in the sub-tasks, and then even more time to edit it to make it flow. Then maybe you had to add some concepts you overlooked. And then pictures. And then diagrams, and maybe flowcharts.

Plenty of diagramming applications will render a nice graphic. Plenty more will make a pretty flowchart. A few will even provide graphical, step-by-step guidance. One of these is a neat new web-based tool called Navitome. Navitome facilitates the creation of walk-through guides to explain a process or procedure. It renders any process into step-by-step workflows and tasks in clear, graphical, click-through guides.

Navitome is a startup out of Cambridge and a 2015 MassChallenge finalist. I recently did some independent contracting work for them, creating process guides and video tutorials. I’m not getting paid to write about their product; I really just find it a cool web-based tool that technical writers and instructional designers will find useful and easy to work with.

I used Navitome to make a process guide that teaches the process of performing an information-security audit. Here is a screen shot of part of the guide from the author’s point of view:

Screen shot of part of the guide from the author’s point of view, showing the sidebar and the main workspaceNavitome

Basic components are created on the sidebar and moved into place in the main workspace

Three basic components (workflows, tasks and questions) are created on the sidebar and moved into place in the main workspace. Tasks are the basic components; these are organized into workflows. Questions, or decision points, lead learners down varying paths, depending on their answer. For example, to decide how to do an information security audit, it’s necessary to identify which type of data an organization stores. That’s where the question comes in: What type of data does your organization store? If the answer includes “sensitive data that belongs to outside clients,” then the learner is led down the relevant branch of the process. If the answer is “We store only our own information — no client data,” then the learner is led down a different branch. The cool thing about Navitome is that you can create your process parts loosely or in order. It depends on how you think through the process. You can move workflows, tasks, and questions about, which makes it easy to add stuff later, or completely reorganize the process. It’s also possible (and easy) to incorporate images, videos, links and downloadable documents. Interactive features can be integrated in to a process, like checklists, text inputs, multiple-choice questions, and file uploads.

You can load more in-depth information into “learning libraries” that link to relevant parts of the process. For instance, I set up an “Information Security Worksheets and Links” library that came into play during various steps of the process, and that could be reached at any point in the process.

Here is a screen shot of one of the tasks in a workflow:

One of the tasks in a workflow

I worked on my guide with two remote subject-matter experts by giving them “author” access. When we were ready to go live, I just chose “Publish” on my dashboard.

Navitome also has an analytics dashboard that lets you monitor and track user progress and bottlenecks in each of your guides. You may also collect data submitted through web forms in your process. The data can be exported to a spreadsheet.

To see Navitome’s process guides in action, take a look at the guides created by Exceptional Lives, a nonprofit for families of children with disabilities. The people at Exceptional Lives created easy-to-follow guides for parents.

About Regina DeAngelo

Regina DeAngelo is a writer living in Charlestown, RI.