Who needs Simplified Technical English?

Over at Clever Hamster, there’s a description of Simplified Technical English and what it’s good for.

Simplified Technical English is a writing standard created for aerospace/defense maintenance documentation, born of a deadly need for clarity (such as the worker who obediently “cut the power” with loppers and died). It’s a controlled language because it restricts grammar, style, and vocabulary. Its goal is to stamp out ambiguity (one word = one meaning) and present technical complexity in the easiest language possible, to support users of diverse ages, abilities, and familiarity with English.

When cats help you cook

more funny cat pictures

Recipes are a common example of writing a procedure. What makes a good recipe makes a good procedure. It states

• Expected results: serves 4, low-fat, children like it
• When to use it: you’re in a hurry or you have the oven on anyway
• Requirements: preparation time 20 minutes, cooking time 1 hour
• Materials needed: list of ingredients and how they’re prepared (e.g. chopped or sifted)
• Actions in order: steps in chronological order for best result: preheat oven, then mix dry ingredients.
• How to know when you’re done: golden around the edges

When you think about writing a procedure, don’t be intimidated: think of it as a recipe for results.

There’s a wiki in my future

My latest contract assignment is as part of a team writing Help Desk training materials for dozens of legacy applications served over a wide-area network and used by different companies in the newspaper publishing business. After much debate, the project managers settled on a wiki–web-based, collaboratively written pages– for developing and delivering content. Everything from the first draft will be online, available for review. Later, it will be updated by the users themselves as they gain expertise. It’s going to be interesting!

What is a reflow?

On Doug T.’s blog, you can learn about reflows: what is a reflow and how are they calculated?

Hint: a reflow calculates where elements are placed on your screen.

There’s also reflow for PDF files and for images.

STC Toronto: The Power of Podcasts, May 13

Podcasts are seen as a platform for reviews, opinions, and polemic. But they can do much more. This presentation helps you discover how valuable podcasts can be.

Podcasts are the next step beyond blogging. But they are also a powerful platform for training and user assistance. They are useful whether you’re a technical writer explaining how an application works or a marketer expounding on product benefits.

Aaron Davis and Scott Nesbitt will examine how you can tap into the power of podcasts. First, they’ll explain what podcasts are and how to create one.

You’ll learn how podcasts

• Can help maintain an ongoing dialogue about a domain or topic
• Are a great way to disseminate new developments
• Serve the users’s convenience by being available anytime, and anywhere
• ake supplementary material more interesting

Aaron and Scott will

• Outline the mechanics of podcasting
• Point out some of the popular training and educational podcasts on the Web
• Analyze why these podcasts are successful
• Tell how you can use the same techniques with your audio materials

About the presenters: Aaron Davis and Scott Nesbitt are partners in DMN Communications, a technical communications consultancy in Toronto. Since 2006, their podcast, Communications from DMN, has been entertaining, informing, and occasionally annoying a diverse global audience.

The meeting will be held in the Burgundy Room at the North York Memorial Hall, 5110 Yonge Street, concourse level, at 7:00 p.m. General Admission is $5; STC Members attend for free.
For directions, visit STC Toronto and click on “Meetings.”

Ten Plagues of Technical Documentation

In honour of Passover, Andrew Brooke has written an article about The Ten Plagues of Technical Doucmentation. Andrew is a senior technical writer and a member of STC Toronto,

Wednesday workshop: peer-to-peer editing and self-editing

This half-day workshop ran on Wednesday morning atl Front Runner Training for STC members.

Content

• The importance of effective peer-editing or self-editing in today’s business climate
• Effective production checks
• Individual exercises simulating a production check
• What to look for when editing or proofreading
• Estimating time frames and adjusting the level of editing
• Examples of common mistakes
• Style issues and style guides
• Improving your proofreading skills
• Working in a shared authoring environment, such as using a Content Management System
• Individual proofreading exercises

About Ed Marshall,
Ed Marshall is an independent consulting writer, with over 20 years’ experience writing and producing documentation for highly technical products including Application Programming Interfaces (APIs), Java-based products, Software Developer Kits (SDKs), Web Services, and other tools for developers. He has presented talks at local chapters of the STC, STC Conferences, the WritersUA Conference, and the Pubsnet Conference. Ed lives in Boston, where he operates Marshall Documentation Consulting.

STC Toronto meeting: APIs and SDKs

At today’s meeting, Ed Marshall speaks on “Documenting APIs and SDKs: Breaking into and Succeeding in a Specialty Market.”

Looking to earn more money? Increase your knowledge of the technical side of technical communication? Looking for more flexibility in what you can offer an employer? Trying to get your employees up to speed on API’s and SDK’s?

Writers should consider this area as the demand for writers is often greater than the supply; hence you they get higher pay than for other types of writing. Also, they often get greater flexibility in telecommuting or working remotely.

During this talk our speaker:

• defines defines application programming interfaces and software development kits
• explains the differencs between APIs and SDKs
• identifies the benefits and drawbacks to doing this type of writing
• discusses the types of personalities that thrive in this environment
• provides sources of training
• explains logistical issues unique to these products
• mentions commonly used tools to generate the documentation

Ed Marshall is an independent consulting writer with over 20 years experience writing and producing documentation for highly technical products. They include APIs, SDKs, Java-based products, Web Services, and other tools for developers. Ed has presented talks on source code control, developer documentation, and editing / proofreading at the local and international levels of the STC and demonstrated several of these areas at the WritersUA Conferences.

The meeting will be held at the North York Memorial Hall, 5110 Yonge Street, concourse level, at 7 p.m. General Admission is $5; STC Members attend for free.

Are you really a tech writer?

There are some people who seem to know the Mysteries—the inner workings of the world, such as what makes traffic lights change and why there’s less air pollution now than there was thirty years ago. And they’re not scientists.

Andrew Brooke has a simple test to help you find out if you’re really a tech writer.

Using Madcap Flare with FrameMaker

Andrew Brooke has written a detailed critique of using the XML-based online-help system Madcap Flare with Adobe FrameMaker publishing software to create both online help and technical documentation from a single file. This is known as single-sourcing. The ideal is to write once, then export many subsets of the content into a variety of formats.

Andrew’s review focuses on using Flare with imported FrameMaker files, a task most writers will have to do if they switch to Flare for their online help. Apparently, there are still a few glitches in the process.

Andrew Brooke is a senior member of the Society for Technical Communication in Toronto.

STC Toronto meeting: How to Increase your Odds of Project Success

Tomorrow’s meeting: The Importance of Being Earnest (about Documentation Planning) or How to Increase your Odds of Project Success

Our Speaker: Vivian Aschwanden, Senior Information Developer, Platform Computing

Vivian has worked for over ten years in the field of technical communication in both writing and leadership roles. For the past three years she has worked as a Senior Information Developer at Platform Computing, a Markham company that develops high-performance / grid-computing software. Vivian began her career as a lone writer for a software startup in Northern Ontario before moving to Toronto to develop documentation for a broadcast engineering firm. Ready to take on new challenges, Vivian earned her CAPM credential (Certified Associated in Project Management) last year, and intends to one day become a full PMP (Project Management Professional).

Outside of work, her current projects include house training Boomer-the-puppy, managing her 9-year-old son’s multi-sport schedule, and keeping her husband toeing the line at home.

Topic Details:

We’re called technical writers, documentation specialists, information developers, authors, and communicators. Titles like these downplay the fact that we are also tasked with project management, not just writing. For our documentation projects to succeed, we must not forget to wear the PM hat.

During this session Vivian shares some of her project management knowledge, applying it to the everyday world of the technical communicator. More specifically, she examines the nine Project Management Institute (PMI) knowledge areas that every good project manager (and technical communicator!) should consider during the planning phase of a project:

• Scope
• Time/Schedule
• Cost
• Quality
• Risk
• Procurement
• Human Resources
• Communication
• Integration

Successful documentation projects must consider, plan, and manage each of these knowledge areas. To ignore any one of these areas during a project’s lifespan could result in a once on-track project becoming a troubled project. After discussing effective project planning and implementation during the first half of the session, Vivian flips the coin and spends some time on the dark side defining troubled projects, their symptoms, and causes. The evening wraps up by discussing recovery strategies and opening the floor to questions.

The meeting will be held
at the North York Memorial Hall, 5110 Yonge St., Toronto ON,
on Tuesday, March 11, at 7 PM.
General Admission $5/STC Members attend for free.

— Thanks to Todd Race for the programme listing

Technical writers: dealing with stress

Warren Singer has written a detailed article on TECHWR-L about how technical writers can deal with the kinds of stress that come with their jobs. He gives detailed hints for these strategies:

• Managing Your Time and Workload Efficiently
• Coping with Last-minute Changes
• Increasing Your Access to a Product and Understanding of a Technology
• Handling Subject Matter Experts
• Managing Your Manager
• Minimizing Computer Problems
• Making the Best Use of Your Workspace and Desktop Equipment
• Enhancing Your Job Security
• Coping with Poorly Defined and Managed Projects
• Increasing Your Control Over the Work Environment
• General Strategies for Coping with Stress

Technical writers: stressors

Warren Singer has written a detailed article on TECHWR-L about What do technical writers find stressful about their jobs? Warren Singer has written an article on TECHWR-L, examining the factors:

• Work overload and time pressures
• Last-minute changes
• Difficulty with Subject Matter Experts (SMEs)
• Problems with managers
• Ongoing learning challenges and limited access to a product
• Poorly defined and managed projects
• Computer and tool problems
• Workspace environment
• Job security
• Lack of control over the work environment

Content Convergence and Integration conference

Content management professionals have an opportunity to learn and share expertise in Vancouver March 12 - 14. The idea of convergence and integration of content stems from the very real advantage of re-using topics, definitions, tutorials, and the like in different contexts after pulling them from different sources.

Content Convergence and Integration 2008 is for content professionals who need to find more strategic ways to manage their content in a world where content now gets created and syndicated, integrated, repurposed, and redistributed. Content professionals, from Web to marketing to technical communication professionals, from content management to knowledge management to information management consultants, are searching for new techniques to stay ahead of the curve.

The conference tracks, appropriately enough, converge into three daily themes: Content, Technology, and User Relationships.

The agenda looks very interesting. The Content track has an emphasis on XML and classification of information.

FrameMaker Chautauqua 2008

The 2008 FrameMake Chautauqua takes place February 14 and 15 in Raleigh, North Carolina, U.S.

Loosely put, a chautauqua is a traveling meeting designed to spread the word. For this event, it means “a convergence of FrameMaker users and certified experts to share knowledge, network, and hear Adobe speak on the future of the product. “

Keynotes and General Sessions:

• RJ Jacquez, Adobe Systems Inc.
• Maxwell Hoffmann, Welocalize
• Kent Taylor, acrolinx
• Russ Ward, West Street Consulting

Presenters (listed alphabetically)

• Bernard Aschwanden, Bright Path Solutions
• Donna Cuyle, The Raymond Corporation
• Frank Elmore, Elmsoft
• Mike Feimster, ACS Technologies
• Kevin Gibson, Bright Path Solutions
• Ann-Marie Grissino, Keypoint Consultants, Inc.
• Maxwell Hoffmann, Welocalize
• RJ Jacquez, Adobe Systems Inc.
• Scott Prentice, Leximation
• Lynne A. Price, Text Structure Consulting
• Martin R. Smith, Apex CoVantage Inc.
• Kent Taylor, acrolinx
• Andrew VanConas, Quadralay
• Leigh White, Misys Healthcare
• Ann Zdunczyk, a2z Publishing
• Russ Ward, West Street Consulting