When technical communicators chat amongst themselves, vast quantities of really valuable information can be passed along, about tools, management techniques, trends, and lots of little ways to make the job go more smoothly. In 2011, Techwhirl’s email discussion list continued to provide a treasure trove of opinion, facts, recommendations, suggestions and ideas. As we close out the year, we thought it would be worthwhile to mine this vast expertise and provide you with some wide-ranging tips and tricks you can use in 2012 and beyond.
Create Terminology Standards to Streamline Documentation Processes
It may seem like a no-brainer—have terminology standards. However over time, new SMEs, tweaks, revisions and assorted new releases can cause terminology standards to deteriorate. When Julian Cantella asked about terminology choices in September, he was asking from a documentation/product quality perspective including sources and enforcement. The guidelines provided by Gene Kim-Eng and Mark Baker are worthwhile whether you’re starting a terminology project or planning on a refresh.
Set terminology standards for documentation with a prioritization that supports your organization’s objectives.
- Brand identification: if any of our terminology is something that we have registered or trademarked, that’s choice #1.
- Industry standards: common terms familiar to our expected user base.
- Plain English (or other language): never make up new terms for anything that already has a name your readers will understand (unless they fit into 1 or 2 above).
- Simplified technicalese: if there’s no terminology that fits into 1-3 above, take developers’ terms and tweak them until you end up with something that does.
Mark Baker elaborated on 2 and 4, recommending that technical communicators use terminology of the user community (whether plain language or specialist) and the terminology used in the product interface.
Develop a Skills/Competency Matrix to assist in managing teams
One area of recurring debate on the TechWhirl discussion list covers the pros and cons of quantifying technical communicator performance. Relative merits aside, those with responsibility for managing teams need ways to quantify performance to stay in compliance with HR and management directives. When Tony Chung asked about objective measurements to justify salary increases, Bill Swallow responded with a “loose” set parameters that should be adaptable to the specific needs of a team.
- Domain experience: knowledge and understanding of the company, its place in the industry, current issues, various stakeholders or audiences, and their needs and expectations.
- Writing ability: Including efficiency at producing content, quality of content (e.g., level of editing and revision) ability to follow the style guide, impact on translation and localization processes.
- Technical ability: Range of and proficiency in tools required to perform the job. This can also include “any additional tech knowledge outside the writing world that is of use” within the tech comm team or the overall organization.
- Social skills: Ability to interact with the immediate team and with other groups, and willingness to drive collaboration among departments. Swallow emphasizes that social skills should not be overlooked “Do people enjoy working with the person?”
- Additional responsibilities: Willingness to contribute to projects outside the technical communications area, such as working with other groups to solve internal or customer issues or contributing to process improvements.
“Those are all things I used to evaluate on,” Swallow said. “And yes, I had a skills matrix that I updated and referenced regularly. I used this to keep track of who knew what, so if a question or issue arose, I knew who to pull into the discussion. Quite handy when you have 25 people scattered across 5 time zones.”
Find Alternatives to Less-than-perfect Prescription Glasses for Computer Use
Let’s face it, if you work on computers long enough, you will find the need for some “assistance” in seeing the details on the screen. Eyestrain is a hazard most technical writers have to deal with regularly. Robert Lauriston, Michael Wyland, and Mark Baker provided some great alternatives to making do with the reading glasses. Lauriston said, “At work, where I need to switch between the computer and talking with people, I use what you might call modal bifocals that have two pairs of lenses, hinged together at the top. Flip down the second set, it’s reading prescription; flip them up, it’s distance. Before I got those, I was constantly misplacing one or the other pair.” Wyland said that he “opted for a variation of the prescription reading glasses approach,” requesting a prescription that was optimized for the distance between his eyes and the computer monitor. “They’re a slightly different prescription than my bifocals, and they work GREAT.”
Mark Baker decided to look for an alternative approach after reading up on the ergonomics of monitor placement. (http://www.ankrumassociates.com/articles/setting.htm.) “Having read this, I took the base off my monitor, slammed it right down on the desk to make it as low as possible, and also pushed it as far back as it would go. I have not needed the task glasses since. I keep my regular progressives on my nose at all times and never have an issue with visibility or eyestrain. I highly recommend trying this approach.”
Include Labeling as Part of Your Documentation Set
In a thread entitled “How/where would you handle this documentation problem?” one suggestion veered from the central question of maintaining a compatibility list to designing a small label to prevent users from improperly inserting a card into a PCIe video slot. Remember to include packaging and labels in your documentation planning. Labels have one big advantage over manuals with warning messages—they’re documentation that stays with the product. That’s important particularly for products that received, opened and installed by different personnel in an organization. The original poster, Kevin McLaughlin remarked “Technical communication that doesn’t involve books or web pages, or even videos. Cool.”
Learn Use Word as a Publishing Tool
Many technical communicators work in environments where it can be impossible to get the budget for the authoring and production tools that are considered best of breed in our industry. But as Rick Bishop explains, it is possible to use ubiquitous tools such as Microsoft Word to do specialist jobs. He noted “Word can produce ‘real’ books. I’ve produced several commercially printed soft cover books with it (hundreds of pages and numerous illustrations). Word can produce a textbook layout and format as well as InDesign, Frame, or TeX in every respect but one. That is that Word does not do proportional spacing very well. This means that when you full justify text on the printed page, you may occasionally see a ‘river of white’ running down the page.” Word includes functionality to lay out text “Like WordPerfect 6” in the options, which Bishop notes is still not quite as good as a true layout program. In environments where perfection is willingly sacrificed for speed, Word can do surprisingly well. Finally, “If you demand perfection, go with one of these and import the Word documents as source materials. The styles can be mapped on import, shortening the production time considerably – especially if there are multiple authors. I will say that no one noticed this spacing issue on my books produced in Word except me (finals to the authors and the printer were in pdf), and the printed copy was quite good.”
Make Use of Adobe Acrobat Shared Review
All technical communicators go through some sort of review process, and Shared Review functionality within Adobe Acrobat is useful for tracking who is doing the reviewing, and the content being reviewed. When a review process is complete, ensure you are discarding unneeded review copies. Britton Hanson recommended that “Once you have a copy saved, remember to “End Review” and “Remove Review from Tracker” (both are right-click actions). This ensures that the review is actually gone. You will still have files to delete, but the review will be over for those documents.” This is one mechanism that combines streamlining the review process with version control.
Plan SharePoint Site Organization
Whether it’s because they recognize the value of the technical communicators’ skill sets, or because they want to offload a thankless task somewhere, organizations often assign managing the repositories of technical content to the technical writers. , To manage version control and maintain findability, a good organizational structure is paramount. When Nina Rogers was tasked with organizing her company’s SharePoint site, Keith Hood put on the information architect badge and put together some recommendations for implementing a structure.
First, lay out a directory structure, or folder tree, before starting to move content around. “Talk to the people who will be using the documents, and organize a structure that helps support the work. You may organize things along technical topic lines, or along project-related lines, or along work division lines” (e.g., network support and database design). He recommends starting with a structure that aligns with the actual work processes in place.
And, it’s critical to get the support and approval from management in advance of implementation, where you (or your team) have been designated as the manager(s) of the site. Hood pointed out “That may mean you wind up doing a lot of librarian work putting documents into the folders, but you can’t afford to have too many people involved. The degree of organization is always inversely proportional to the number of people who are allowed to change things.”
Most important, develop, post, and maintain an easily accessible document that organizes the documents and provides links. “I put up a spreadsheet at the root level that gives links to each individual document, and links to the different folder levels. Plus, it has various criteria columns that are filtered, so that someone who doesn’t know the document title or the folder it’s in can sort the spreadsheet entries and zero in on it that way.” For easier maintenance, use the SharePoint alert functionality to monitor changes and movements of documents. And take advantage of the workflow features to set up document review processes.
Quick Screen Capturing of Remote Desktops
If you work with Windows Remote Desktop and need to capture screens in Windows mode, here’s a handy keyboard shortcut that ensures you can capture the remote active window, rather than the whole screen: Ctrl-Alt-Minus sign(-)
Remember, PrintScreen captures the full screen on your own computer, and Alt+PrintScreen captures just the active window. The default keyboard shortcuts for Remote Desktop are listed in a MSDN knowledge base article located by Sandy Shew in response to Dan Goldstein’s question. http://msdn.microsoft.com/en-us/library/aa383500%28v=vs.85%29.aspx
Take Simple Steps to Move to Structured Writing and Content Management
DITA, structured authoring, content management… for technical communicators in lone-writer, low-budget, or less-than-current technology environments, these concepts can be pipe dreams and more than a bit daunting. Management may decide they want the latest, but getting there and making it a worthwhile investment take huge amounts of time and money… right?
Not necessarily, when Michelle Vinas-Baltas asked the list “Is it required to have a CMS in place before going to a structured/XML/DITA environment?” Bill Swallow and a few other Whirlers responded with recommendations to get started, no matter the size of the company, the tech comm group or the budget. “But even if you’re a small shop with more than one author, you can get by with using a branch of your development team’s version control system. As you get comfortable/grow your content authoring practices you will likely find a need to move to a CMS, but to get started all you really need is a home for the content and either a solid communication plan among authors for working with the content and/or a version control system for checking in/out files.”
A special thank you to Adobe Systems, Inc. for sponsoring our Tips & Tricks column. You can learn more about Adobe’s industry-leading technical communication tools by going to their website.
