... in the world of Technical Communication

“Can we change this document type?” was the comment I recently heard from a project manager during a weekly status meeting. “I know that’s the type we’ve used for all the other documents, but some of our users for this project call this document something else. Maybe we should try to align the terminology with theirs for this project.”

At first listen, I cringed internally at the suggestion but smiled and quickly planned my reply. “Well, it’s a good suggestion, but I’ll need to take this back to the department to discuss that change. We’re beginning the process of standardizing the types of documents we release, so any change to our current document types need to be approved by our department first.” The PM was a bit frustrated because she figured it was a lost cause and wouldn’t go any further. After the meeting, I pulled her aside to further explain our reasoning for not changing document types on a project by project basis – long-term it causes confusion for the user and makes the documentation set overall much more difficult to manage and standardize.

In many corporate settings, documentation is a challenge to manage as it is. When the documentation department lacks clear cut standards as to the types of documents they produce and the contents of those documents, it adds to the overall confusion – for both the users and the writers.

One of the first steps to standardizing or formalizing a documentation department is to establish clear cut document types. Generally, I recommend the organization look at the types of documents they have produced in the past and begin to categorize them. For one organization, we found we had documents called Admin Guide, Install Guide, Implementation Guide, and User Guide. Through our discussions, we found that the Admin Guide and User Guide were unique document types. Admin Guides always contained system administration information. User Guides always contained end-user guidance.

When it came to Install Guides and Implementation Guides, the discussion was a little more complex. After various discussions, we decided that these two guides contained roughly the same type of information – information used to implement a software package at a site. The group felt that installation of the software was just one small part of an overall implementation, so they decided Implementation Guide was the term they’d use going forward. That process was repeated for the 30+ types the group identified initially.

Now, this may sound like a lot of work to simply determine the standard types of documents these writers produced. However, the long-term benefits of such discussions are numerous:

1. Management has better oversight into the types of documents the department produces. Management can pull a variety of metrics to share with executive management about the productivity of the department.
2. Writers become empowered. Writers have a solid “menu” (so to speak) of the types of documents they write. Thus, when they interface with the business they can comfortably explain the standards. If a project wants something outside those standards, the decision to escalate the request to documentation management is clear cut. The writers retain their “document expert” status while management gets to handle those strategic decisions.
3. Users experience less confusion. Users like consistency. Knowing they can find a certain type of information in a specific type of document reduces the amount of time users spend “looking” for the document they need.

The organization as a whole also benefits through this type of standardization. When standards are implemented and followed, employees spend less time making those strategic decisions on the fly to fit an immediate need. Instead, they are empowered to select the right “tool,” or in this case document type, for the project. Time isn’t spend debating what they should call the document, what should be in it, whether it needs to be two documents or one or four. They simply reference the outlined standard and any issues are escalated up to management where those decisions should be made so they support the whole documentation set, not just the current project.

While it takes time, coordination, effort and compromise, standardization of document types is a win-win for everyone involved. Oh, and that project manager who wanted to change the document type – after she listened to my reasoning and spoke more with the documentation manager, she better understood our purpose for keeping things consistent. And the documentation department developed 22 standard types of documents (down from 40+) they produced for the various business lines and software they supported. I’d definitely call that a success!

Ever since I chose to pursue a career in technical communication (at the time simply called Technical Writing), I’ve been very interested in how we as communicators add value to an organization. It was the topic of my final project to get my degree and a concept I’ve pursued at each organization I’ve worked for or consulted with.

Recently, I’ve been engaged with a training and documentation department at a large healthcare provider out of Nashville, TN. Like many large organizations, the learning department within this organization is struggling to identify how to engage in more a meaningful way with the various project teams. I am specifically helping them to understand how to better utilize their documentation staff. Since many of the issues I’m helping this organization work through relate to increasing the value their writers add to the organization, I thought I would share some of our challenges and successes!

The Background

When I first started working with this organization, I was told there was a lot of work – more work than the staff could handle but they were having a hard time justifying additional full-time resources. They knew the work existed, but couldn’t predict the frequency, projected hours, time frames, etc. Since there was so much work, the two writers engaged with clinical systems were mostly relegated to editing and fixing formatting for end user documentation the product development team wrote. The main complaint was that they weren’t writing – they were simply glorified editors and formatters.

What was even more interesting was when I asked why the writers weren’t more engaged in the development process, I was told it’s because the Business Analysts (BAs) didn’t want to give up the task of writing. That single statement made me stop and wonder what was really going on within this environment because that is the first time I’ve heard of a whole department of BAs WANTING to write the documentation. This just didn’t fit with my prior experience where everyone was more than happy to give up writing the documentation because that was their LEAST favorite task. (I generally get good-naturedly teased about actually enjoying writing the content!)

There are always two sides to every story, so I asked to engage as the writer on a short but high-pressure project with one of the core development teams. I believe there’s no better way to truly understand what’s going on in an environment than to become immersed within it. A few weeks later I had my first meeting with the BA team. During that planning meeting, I listened as they outlined the process they generally followed to create documentation – each BA wrote their piece. They would send it to me and I would do a quick edit and compile into one document then publish. I quickly spoke up and asked if they would be willing to try a variation of that process – I work with them to develop the content and assemble the document. Essentially, it becomes a team effort instead of each individual doing siloed work in a more linear format. They agreed to try it out.

The Results

The results were spectacular! The BAs more than happy to give up the process of managing and creating the content on their own (which is what I suspected all along). I also found out that many years ago, the content development process worked this same way for all projects. Over the years, the system slowly degraded to the current system. All agreed that working closely on documents freed up the BAs to focus on the tasks they were ultimately responsible for (writing requirements and specs, supporting business owners, etc.) and allowed the writer to do what they specialize in – author content and manage the document development. It was a win-win for everyone.

As I related these large and small successes back to management within the learning organization, I noticed that I still hadn’t written a lot of the content. The BAs, who know vastly more about the application than I ever will, provided me with the base content. I edited and supplemented what they gave me, but the real value I added was providing a single point of contact for everyone on the team regarding the documentation. I facilitated (and, I’d argue, improved) collaboration both within the BA team as well as between that team and the outside business entities involved with other aspects of the overall project.

The Lesson

This increased facilitation yet lack of writing got me thinking about the overall value and role of technical communicators within large organizations. This is not the first time I’ve seen this in a large company. Last year I worked with an auto manufacturer in their corporate IT department. While I was hired to write documentation, most of what I did was facilitate collaboration between the enterprise architects and the business. Since they determined and distributed standards, they needed to sound like experts – so I helped craft the documents to be effective and informative communication tools. I did some writing, but it was more helping the architects convey the information they needed to convey, the exact same thing I’m doing for the healthcare organization.

My takeaway from both these experiences is that as technical writers we must stop thinking about simply authoring content and start thinking about how we help to convey technical information throughout the organization. This is where our real value lies. Many people can write these days. We as technical communicators set ourselves apart by understanding how to bring the various pieces, parts and people together to craft documentation that facilitates learning at every level.

The next time you or your writing team complains that they are not doing enough writing, take a look at your overall process and determine whether writing is the best way to add value to your organization. Like me, you may find that the real value of your writers is not actually writing, but facilitating the collaboration process within your organization.

I'm part of a couple different groups on LinkedIn. Recently, a thread was started entitled: "Hi All: Is working remotely a common situation for a technical writer who has a fulltime position in an organization."

The topic was posed by a college-level professor who teaches technical writing. From the sounds of it, she was wondering what to tell her students about this subject. There was a great community response from the post - lots of professionals posted their experiences, likes and desires. Since I'm a big fan of working remotely, I weighed in on the topic and I thought I'd also share my response here...

"I agree - while working remotely is becoming more common within technical writing, it is by no means normal or should be expected. One of the reasons I started my own freelance technical writing/training solutions company is to add more flexibility into my schedule. Writing in an 8-5 environment is often hard and I like the flexibility of being able to walk away for an hour or two then coming back and working until 9pm - essentially working to be productive instead of simply putting in "standard" work hours.

Being a freelancer takes the focus off of the hours you put in (I put in far more than 40 hour weeks!) and focuses more on results – often those results take more or less hours than you anticipated. I find I’m much more productive when I’m not required to put in X hours. A career coach once told me that you can stretch out any task to fill the hours. I’ve found this is so true! When you’re freelancing and building a solid client base, your time becomes much more valuable, thus you learn to be very productive with your time.

However, the declining economy has led me back to a more corporate setting and I was lucky enough to land a contract with a company who has an established work from home program. I work at least one day from home, sometimes two depending on the current projects (often more on various weeks if I'm working on training videos since the dept does not have the audio equipment & software set up I need to produce what they want.) I find that I don't like being away from the office more than 2 days a week - I lose touch with the ever-changing environment; and, unfortunately, the culture that exists at this organization still wonders if you actually "work" while you're at home.

To combat this, I try to target my home time for projects that are difficult to do in a cube setting - editing (because it's quiet) or writing (at times). And I make sure I'm available via the corporate IM solution just like I would be in the office. It does require a good amount of trust - and that trust has to be keep up long-term (at least within my current contract) as it is fragile. Once doubt enters into your manager’s head that you’re slacking off during work from home days, it is very hard to overcome; better to not let that doubt enter at all.

I was disappointed to read that some employers might think of a candidate as “high-maintenance” if they ask about working remotely in during an interview. When I interview, I strive to be honest and up-front about what I can do for the company and what I need to be a highly productive member of the team. Work from home is important as I live an hour a way from most major employers and a 2-hour commute daily makes it hard to keep a work-life balance and take care of my family. A strict M-F, 8-5 environment would be hard for me to work within long-term. Short-term it’s essential to learn about the new environment, product, project team, etc. Long-term, it would burn me out.

As for students or those new to technical writing, I think being on-site is ESSENTIAL for the first 2-5 years (or longer, depending). Especially for those coming out of college, working in a corporate environment can be overwhelming - the work & deadlines combined with the new social and political situations. You need to be on-site, listening, learning and being part of that culture so that you can learn how to continue to engage with that culture if you get the privilege of working off-site.

Working remotely is definitely an art - you have to learn how to do it effectively, make mistakes, learn from them and move on and be VERY conscious of your productivity and your interactions with your team and clients. My hope is that those of us who are successful freelancers and/or who work well outside a typical office setting continue to foster trust, be highly-productive and make a good name (so to speak) for working remotely within this industry."

If you have an opinion or questions about freelancing or working remotely, leave a comment, email me or join the LinkedIn group and post a message.

In today’s corporate culture, managers and executives are looking for more and more ways to minimize costs and maximize output. When it comes to technical publications (both print and interactive electronic), writers and designers need to think outside the box to author and design materials to suit a wide variety of uses.

Long gone are the days where you had a separate user manual (for reference), training manual (for users taking a class), quick reference guide (to use as a desk reference), governance policy, etc. Today, one publication or e-learning course should satisfy at least two or more training and knowledge transfer criteria. So how do you do this?

First, think about how each different type of publication will be used. To continue with my earlier example, user manuals are most often large, comprehensive reference manuals. Users go to them when they can’t figure out how to perform a specific topic. Sometimes new users are instructed to “read” the whole manual before they begin a job or task. (We all know users rarely read these publications cover to cover!)

A training manual is often more interactive as it’s generally used in a classroom or online learning environment. It may present the same information as a user manual (maybe even use the same exact content if the organization has a good content management system), but is supplemented with hands on activities or tasks a user should perform to familiarize themselves with the topic being discussed. These manuals are often more graphical or have more callouts, notes, and icons to help guide learners through each module.

Quick Reference Guides, cheat sheets and the like are often prized by users. They are generally short and concise and provide quick reminders about how to perform common tasks. Like the training manual and the user manual, these quick reference sheets may contain the EXACT same content as other publications within the organization. When you look at these three types of publications as a whole, it doesn’t seem like a very efficient documentation process.

So what if we combined a couple of these documents into one power publication? What you get is an extremely dynamic manual that has multiple uses within an organization. But how do you combine all that information into one format for different audiences?

Organization is a key factor when approaching a power publication. I’m currently working on a user guide for a software program that will also serve as the main training manual for instructor led (ILT) courses. The organization already knows that not everyone will be able to physically attend the classes but they wanted these users to have a similar learning experience.

Step 1: I started with the concept of a user manual. The first objective is to explain all the features and functionality of the software, top to bottom. This ensures the manual contains everything a user might want to know about how to use the program.

Step 2: I then added the organization-specific standards and governance policies regarding that software. This includes things like where to store reports a user creates, naming conventions, etc. This makes the manual extremely relevant for the users. They now only have to go one place to view the organization’s policies on tasks as well as view instructions on how to perform that specific task.

Step 3: Add in practice activities. In the current project, we call them Practice It! activities. The organization set up templates, sample reports and dashboards in a “training environment” within the software that all users have access to. In each section, we indicate how to use the templates or reports to practice, step by step, the steps for each task or process. Since the training environment uses real data, users get a good feel for how they might need to set up reports for their individual business units. These Practice It! exercises are also what the instructor uses during any ILT classes. Now users can get a similar learning experience without having to attend an actual class. To help users distinguish these practice exercises from the actual task step, we used a different font color/style and icon.

Step 4: Supplement the large user manual with a Quick Reference Guide. In the current project, we decided to keep the desk reference guide a separate publication to simplify distribution through the organization’s existing document management system. Some information is duplicated between the two publications, but the quick reference guide is much more succinct with more graphics and less text.

Step 5: Test and tweak. Documentation and training does not live in a vacuum. The beauty of creating training publications, reference documents and e-learning courses is that they are living creatures that change and grow with the organization. Test your initial format and be open to feedback. Change the document format, layout, and content so that it achieves all the initial goals.

This may seem like a lofty proposition for your publications, but your users and management will be ecstatic when it works well. And it saves you, the content developer and designer, a lot of time and effort in the long run which frees you up to work on more interesting projects rather than continually repurposing the same six documents over and over and over again!

Using styles can be helpful and maddening all at the same time. Styles, like a css sheet for a webpage, enable you to keep your document formatted consistently.

Recently, I gave a quick presentation about using styles in a new template I created for Architects/Developers for one of my clients. Of all the interesting features I showed them, they were most taken with the way I used images as bullets.

For example:

In the image above, the note icon, arrow icon and triangle icon are all bulleted styles that use a clip art image instead of one of the built-in bullet symbols. Using a bullet style instead of individual clip art images enables you to create callouts more quickly when authoring your document. It also keeps your formatting consistent for each callout (since image placement in Word can be kind of wonky).

Setting up a bullet style to use an image is just like setting up any other bullet style. Instead of using one of the pre-set bullets, you can select a symbol image or your own clipart image (as seen above).

1. Using the Styles and Formatting toolbar, create a New style or Modify an existing style.
2. Click Format then Numbering.
   
   
3. Choose an existing bullet style then click Customize.
   
   
4. In the Customize Bullet List window, you have the option of choosing a Font, Character (symbol) or Picture. Click Picture.
   
   
5. The Picture Bullet window appears. Choose from one of the existing bullet images or click Import to add your own image.
   
   
6. The Add Clips to Organizer window appears. Navigate to the directory where your image is located and select it. Click Add.
   
   
7. You’re returned to the Picture Bullet window. Click the image you just added to select it. Click OK.
   
   
8. In Word 2003, you can set additional properties in the Customize Bullet List window. In Word 2007, set the indent and tab space in the Paragraphs and Tabs windows (accessed via the Format drop-down in the Modify Style window). Click OK twice to return to the Modify Style window.
   
9. Your bullet image will be resized based on the font size for that style. Adjust the font size and color, paragraph spacing, tabs, borders, etc. for the style. When done, click OK to return to your Word document.
   
10. Test out your new style in your document. Make any other modifications as needed.