Letter from the Editor

Dear Readers,

RTFM!

Recently, when I was at the gym, I overheard a snippet of conversation. One guy was telling another to “read the friendly manual.” Since I first heard RTFM defined as “read the fine manual,” I’ve heard lots of other f-words in the phrase, and few of them have been complimentary.

But a friendly manual strikes me as a worthy goal, a phrase I would love to hear about what I’ve been working on–and I suspect that other tech writers and editors would love to hear, too.

Currently, I’m working at a start-up on a service manual for hardware. I’m driving my SMEs crazy with questions such as “Why does the field service guy need to know this?” or “How will the field service guy remove and replace this part in order to change that faulty part?” Mostly though, I’m trying to avoid an attitude of “and then a miracle happens” to bridge a lack of knowledge.

Working toward a friendly manual is really a great exercise, especially because I get to learn so much, not only about the product, but about the tools and techniques needed to get there. I hope that you get the chance to write a friendly manual, too!

I’m looking forward to seeing you soon at a meeting.

Marie McElravy, Editor

Letter from the Editor

Dear Readers,

I’m working on a freelance gig for a startup, one that is creating some interesting and complex electro-mechanical hardware with associated software. I’m their first technical writer, but my manager does have an inkling about technical writing and writers, and mostly steps back and lets me ask questions and write; I feel pretty lucky about that.

I feel pretty lucky, too, that I’ve been a member of STC for most of my writing career and have learned some tips and techniques to be more successful. For example, I know that I don’t need to reinvent the wheel with every sentence, heading, step, or list I write, I created a style sheet that defined what those elements should look like almost before I wrote my first word. That’s a tip I picked up a long time ago, and it’s preserved my sanity more than once.

More recently, our chapter had a presentation on using File Properties to store information about the document, such as the part number or the type of manual. That keeps the file name to a reasonable size, but keeps the documentation findable in a search.

The presentations dealing with aspects of preparing docs for successful and less-expensive translation didn’t seem to be pertinent at the time, but I’m so glad to have been there–these documents are planned be translated into multiple languages, and my work to be accurate and excruciatingly consistent will help the bottom line.

Of course, the networking aspects of STC meetings help, too. We’ve talked about dealing with SMEs of all sorts, software that helps and hinders, even how to deal with staying sane during the contracting process. Thanks to all those presenters and attendees who have helped to make this gig a good experience!

I’m looking forward to seeing you soon at a meeting.

Marie McElravy, Editor

Letter from the Editor

Dear Readers,

While catching up on some of my recreational reading, I found this lovely description of system engineering, a profession that is similar to technical communication:

Electronic engineers devise electronic circuitry, gengineers tailor biological organisms, civil engineers designs bridges and dams and space habitats, software engineers write programs, and so on–but systems engineers mostly do not create systems.
Mostly they ask questions.
What are all the functions a system must perform, and are there tradeoffs between those functions? What other systems will this system interact with, and what is the nature of the interactions? Who will use the system, and how foolish are the users against whom this system must be proofed? How reliable must the system be, how will that reliability be achieved, and how will the system behave when, all efforts to the contrary, some pieces break? The only thing other engineers found worse than these interminable questions was deploying a system and then realizing that the questions should have been asked. — “A New Order of Things,” by Edward M. Lerner, Analog, May-September 2006, p. 16; republished in InterstellarNet: New Order

The author, Lerner, brought his background in both science and technology to writing, so he understands that a question, properly asked, can be as powerful–if not more so–than the answer. It can prompt a new direction for thought, which can improve the product and how the user experiences it.

Technical communicators know how to ask a lot of questions, and it’s seldom more obvious than at a monthly meeting. Our February and March meetings featured lively discussions prompted by probing questions of both video as a medium for communication and food as technical subject matter. Our April meeting with Andrew Davis will also prompt questions and discussions in yet another direction; LinkedIn takes networking to new levels and new dimensions. May will bring as an early look at a new tool for managing content and access to it across documents; it’s certain to draw more questions and discussion.

Technical communicators work in so many different areas with so many different tools and so many varieties of subject matter that at times, it’s hard to believe that we share the same profession. However, we do all share one skill: how to ask those important questions.

I’m looking forward to seeing you soon at a meeting.

Marie McElravy, Editor

Letter from the Editor

Dear Readers,

The platypus was discovered in Australia in 1798, but not well-publicized outside of Australia and England until National Geographic published an article in 1939.

I remember learning about the platypus in elementary school. It is an interesting animal that seems to be made of parts left over from birds, mammals, and reptiles. Its snout with a bill looks like a duck, its tail looks like a beaver, and its webbed feet look like an otter. It lays eggs, has fur, and the male secretes venom from a spur on its back foot.

Technical writers are like the platypus; our work has varied parts. We write, rewrite, and edit user, marketing, developer, and knowledge-base documentation for a wide variety of audiences.

Technical writers are like the platypus; our work has many inputs. We seek out subject matter experts from engineering, training, marketing, tech support, and field people. Sometimes, we even meet users and learn about what they need.

Technical writers are like the platypus; our work has many sources. Our source materials include specifications for the latest and greatest bleeding-edge tool, work with the product during development, or even oldie-moldy legacy files from before the turn of the [twenty-first] century.

The platypus is a fairly rare animal, native to Eastern Australia and Tasmania. Technical writers are less rare, found all over the world, but they usually are solitary or in small groups. We don’t need to travel to Australia to meet and network with other tech writers, we can simply come to the STC-SF meetings!

I’m looking forward to seeing you soon at a meeting.

Marie McElravy, Editor