Best Technical Writing Tips and Tricks from the TechWhirl Email Discussion List

In 2012, Techwhirl’s email discussion list was alive with opinion, facts, recommendations, suggestions, and ideas on technical writing, job hunting, planning and production of content intended to help users. 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 2013 and beyond.

How to Start Planning the Next Generation Help System

technical writing help systemWhat would you do if your manager challenged you to take your Help system to the next level, integrating blogs, forums, and video? How would you transform your user guides or Web Help to an experience that engages and “wows” your users? When Roger Goodman asked this question, Jen Jobart expressed that, “as Tech Writers, we are at a crossroads,” and need to rethink the help experience as a multi-way conversation – not a one-way megaphone. What kind of Help system offers up reliable answers to user questions via Google searches, for example? Jessica Weissman responded that the first action should be to figure out if users are struggling with anything in the current system. Any improvements should address the user pain points and retain the lean and direct content. Nancy Allison also encouraged us to leverage the feedback of the user, and ultimately make changes to support what users want and need from Help.

Dimistri Tetsch added that Help innovation is:

  • Adopting a centralized database to store all content
  • Enabling content developers to learn what users search and read
  • Enabling users to add content
  • Rendering the content directly from a server in response to user requests in real time, and not shipping a Help system
  • Allowing users to search and assemble the content they want to view and print

Use Video Resumes to Showcase Your Technical Writing Talent

Yehoshua Paul asked the group if supplementing a resume with something attention-grabbing, like a video, is what’s needed to make a Technical Writing candidate stand out in a job search. If a video is done right and feels appropriate to the company, perhaps it’s the edge someone needs to get the job.

Lynne Wright responded that when she is assessing candidates, she is looking for someone with “the skills to do the job, and the maturity/professionalism to be a solid, reliable, and low-maintenance addition to the staff.” She thinks it’s best to keep it professional, avoid the jokes and, instead, design a website to showcase your creative side.

Will Husa expressed that researching a company before submitting a resume is key: “If the target company is known to be a creative company, then submitting a creative resume would place you at the top of the pile.” Will also suggested using the interview to gauge the company culture, and follow up with a creative “Thank You” card, if it feels appropriate.

Reuse or Rewrite: What’s the Best Way to Announce Product New Features?

Rebecca Bowes looked to the group for suggestions about various approaches to announce features when a new version of a product is released. Are there alternatives to duplicating the content from the user manual in release notes? Paul Hanson replied that it is the responsibility of Technical Writers to describe the benefits of the new software release to users who already have the product and may never read the marketing materials. Steve Janoff suggested reusing the topics from the user manual in release notes, thus duplicating the content and not the work. He feels there is nothing wrong with an alternative presentation of the same content because the purpose of release notes is different from the purpose of the user manual.

Follow Best Practices for Making Hypertext Link Text Useful

Hypertext done right is essential to navigating online Help systems. Often users wonder whether to click a link because they doubt its relevance. Fiona Hanington was wondering if there are best practices for writing the link text such that the users know whether a link takes them to reference, example, concept, or procedure. Julie Stickler suggested using headings to provide context for links. For example:

– [Link – Installing the widget]
– [Link – Configuring the widget]

To calibrate the widget, complete the following steps:
Step 1
Step 2

After you have calibrated the widget you must next [Link – Initialize
the widget] before you can [Link – Use the widget].

A Documentation Manager Is Worth the Investment

How would you convince your leadership team to invest in a Documentation Manager position? This question was asked by Keith Purtell, who was approached by a Production Manager with a potential advancement opportunity to document existing processes for new hires. Leonard Porrello suggested that Keith forge a communication strategy to express the value added by the documentation team in terms of how much the company stands to save. For example, if there is no structure to help new employees ramp up, then a manager can help reduce the associated costs by introducing documentation and processes for new hires. Margaret Cekis proposed teaming up with the Production Manager to quantify the demands of new hire training on the department. For example:

  • What is the average weekly salary cost of the employees doing the training? And how much time would be freed up if new employees could be given a procedure guide to follow, and only ask questions of the other employees when needed?
  • How often are there new employees to train?

Tips for Screening Technical Writing Candidates

Kim Bieler was in the process of evaluating resumes for a Technical Writing and Content Strategy position and asked the group for some tips on screening resumes. Lynne Wright highlighted several characteristics of successful CVs:

  • The cover letter should convey information in a clear and concise manner, worthy of a skilled technical writer.
  • The resume should be well-organized and provide the appropriate amount of detail, indicating the candidate’s abilities to structure and filter information.

Lynne also suggested informing candidates who reach the interview stage that they will be asked to complete short writing and editing tests (which harkens back to some long-lived and heated discussions as well). The writing test could provide the candidate with excerpts from software specification and ask the candidate to write a topic, including any questions they’d ask the subject expert. The editing test would be a one-page procedure with built-in errors of usage, spelling, steps that are out of sequence, and inconsistencies between screenshots and text.

After being hired, the best employees tend to be open to learning and improving their skills. These employees also go the extra mile to ensure that what they produce is as accurate and professional as possible.

If you have never subscribed to the TechWhirl Email Discussion List, you could be missing out on a tip that makes your life easier, opens up an opportunity, or simply opens your eyes to a different perspective. If you were a TechWhirler back in the day, it’s time come back for a visit—take some time to catch up with old friends and new, and revitalize your thinking about our ever-changing field.

Subscribe to TechWhirl via Email