Technical Writing Articles
Authoring in XML — Why Start? by Barbara Stuhlemmer Technical communications professionals had been talking about authoring in XML for a very long time. At first, it seemed like a lot of hype, but that has changed. Dealing with SMEs – Part 1: A Primer for Success by Philip Rastocny Just the thought of dealing with Subject Matter Experts (SMEs) can create stress in the life of any documentation manager. Philip Rastocny provides in-depth insight on how best to deal with SMEs. Dealing with SMEs – Part 2: Selling the Concept to Management by Philip Rastocny Part 2 switches the focus to members of your management team and what you can do to sell your team’s professionalism. Also included are hints on how your writers can individually sell themselves to gain cooperation from SMEs. Do You Have What it Takes to Become a Technical Writer? by Brett Hau You can’t answer this question until you know more about what being a technical writer involves. This article shows you what a technical writer’s skill set might look like and what skills they need. Eliminating the END GAME from Electronic Deliverables by Alan J. Porter While executive management may sometimes believe that anyone can write and that a technical writer’s job is to ‘Just Publish It’, technical writers need to look at what they can do to improve the ‘end game’ process. Estimating a Technical Writing Project: Part 1- The Plan by Robert Klemm Technical writing project planning has several elements in common with any project plan. Yet technical writing project planning also has its own set of elements not found in engineering, construction, or manufacturing projects. This article provides an example of how to go about estimating a machinery technical writing project. Estimating a Technical Writing Project: Part 2 – Details by Robert Klemm In Estimating a Technical Writing Project: Part 1 a few “Key Assumptions” were given to be able to properly scope a project. Part 2 — Details provides a more comprehensive examination of typical variables that impact technical writing project estimation. It’s In the Numbers: Using Metrics to Plan Documentation Projects by Margie Yundt and Sherry McMenemy It’s in the numbers. Creating documentation is not an exact science, yet as communication leaders, we are expected to provide real estimates for how much time we need to document a project, or what we can produce given a pre-determined timeline. Paradigm Shifts are Never Pretty: Advice on Making the Move to XML Authoring by Sarah O’Keefe Most people are risk-averse, and profound changes such as the move to structured authoring require new skills and workflows. To ensure a successful transition, XML implementers need to assess their team members, identify allies, and build their implementation strategy around the staff members who embrace change. Proving Worth: What Technical Communication Managers Must Do to Prove the Value of Their Deliverables by Hannah Kirk Technical communication managers are often required to prove the worth of their deliverables over and over again. The trick to increasing value with internal and external users is to identify areas where documentation can save time and money, to create agreement that the documentation can save time and money, and to ensure that the documentation does save time and money. Find out how. Pulling Facts, Info, and Good Data from Engineers by Lester Stephenson Engineers are great; we couldn’t get along without them. But, the very thing that distinguishes them is also the bane of technical writers. Here is a workable tip that explains a highly successful technique a technical writer has used to pick the brains of engineers for those incomplete sections where there is something wrong, but you’re unsure what it is. Technical Writers are Communicators by WAI Editor Before the emergence of the personal computer, primary technical writer deliverables were operating manuals and instructional guides prepared for print publication. However, an argument can easily be made that even in pre-PC times technical writers were still more than writers – they were communicators. Technical Writers as Subject Matter Experts by WAI Editor Many firms who seek outsourced technical writing help to complete their projects only have the expectation that the technical writer they bring on board will become knowledgeable enough to be able to communicate to the firms’ customers and do an adequate job to get the material out the door. Instead, firms would benefit from viewing technical writers they hire as potential subject matter experts that they’ll use on a regular basis so that the technical writers working for them will become increasingly knowledgeable about the company, its customers, its products and the audience for what’s being documented. Technical Writing and Agile Scrum: Where’s the Fit? by Robert Spielman Why the modern technical writer needs to be part of the Agile Scrum team and closely aligned with the meetings and deliverables contained within each sprint. The Value of Documented Processes by Marcia Weeden How good documentation assists well-planned, business growth, while helping to make business dreams a reality, by providing clarity, history, road maps, insurance, and checkpoints. The Well Written SOP – Critical for Continuous Improvement by Marcia Weeden A well-documented SOP means the company can identify which improvements make the best sense and which will give the best ROI. The well-written SOP is one of the best tools for keeping abreast with change and thus, it is truly critical for continuous improvement. The Why and How of Content Convergence and Integration by Rahel Anne Bailie Industry is discovering content as a commodity; the rules are changing, and fast. What have traditionally been seen as the lowliest form of commercial content within an enterprise – technical manuals – are starting to take their place alongside the other valued corporate assets. Topic-Based Writing to the Rescue: Project Considerations for Managers (Case Study) by Rahel Anne Bailie What do you do when someone asks you to help with a ‘rescue’ project that requires a number of deliverables, including training materials and user guides for a new enterprise system, in under eight weeks? Here’s a case study that details how just such a project can be successful. Which Skill Sets are Important for a Technical Writer? by WAI Editor Like any profession, becoming a technical writer requires a mastery of a certain set of skills. This skill set used to involve primarily writing and illustration skills, as large manuals for print publication were the standard in the profession. The worlds of communications and technology have evolved dramatically in the latter part of the 20th century and the early part of this century. How has that evolution affected the skill set required for a technical writer? Why Audience Analysis is Essential in Technical Writing by Molly Carter While understanding an audience is important in all types of writing when it comes to technical writing, it’s essential to being successful. When you’re a technical writer, knowing your audience determines what information you present, how you present it, and even how you write about it. Why Developers Write Horrible Documentation by Jacquie Samuels Discusses why technical writers – and not developers – should write the documentation. Why Technical Publishing Shouldn’t Be Art by Alan J. Porter Give a canvas and a box of watercolors to a landscape painter and a second-grader. The same materials, the same process, but you get very different results. “Writing is a solitary occupation. Publication is a group exercise,” stated novelist Madeline. Why she’s correct.