SME’s Guide to SME’s Guide to Technical WritingTechnical Writing

Or, [insert funky reset logic]Or, [insert funky reset logic]

The SMEThe SME

SME = Subject Matter ExpertSME = Subject Matter Expert

Studied Computer/Electrical Studied Computer/Electrical Engineering, Math, Physics, Chemistry, Engineering, Math, Physics, Chemistry, Computer Science, and/or Computer Science, and/or Bioinformatics.Bioinformatics.

This is you, or likely will be someday.This is you, or likely will be someday.

The Technical WriterThe Technical Writer

Studied English Literature, History, Studied English Literature, History, Political Science, Philosophy, Political Science, Philosophy, Anthropology, Indonesian Dance, Anthropology, Indonesian Dance, and/or Communications.and/or Communications.

Becoming a technical writer was Becoming a technical writer was probably not Plan A.probably not Plan A. Yes, sometimes they’re still a little bitter.Yes, sometimes they’re still a little bitter.

Technical writers are:Technical writers are: Seldom the first hired to work on a Seldom the first hired to work on a

given project.given project. Often the first laid off when money is in Often the first laid off when money is in

short supply.short supply. Considered a luxury, because in theory Considered a luxury, because in theory

someone else can always do their work.someone else can always do their work. (That someone else could be you.)(That someone else could be you.)

May have a technical background, but May have a technical background, but probably not formally trained.probably not formally trained.

May not understand what you’re talking May not understand what you’re talking about.about.

Want quality documents attached to your Want quality documents attached to your work?work? Teach your writer what he or she needs to know.Teach your writer what he or she needs to know. Make yourself available, provide several reliable Make yourself available, provide several reliable

ways to contact you.ways to contact you.

The Stealth Tech WriterThe Stealth Tech Writer

Never talks about himself or herself as Never talks about himself or herself as a “technical writer” or “document a “technical writer” or “document specialist” or anything close to that.specialist” or anything close to that.

May be an analyst, researcher, May be an analyst, researcher, marketing representative, or even marketing representative, or even manager.manager.

From a practical perspective, has the From a practical perspective, has the same needs as a technical writer.same needs as a technical writer.

This could also be you.This could also be you.

Types of DocumentsTypes of Documents

White papersWhite papers Reference documentsReference documents Internal training manualsInternal training manuals User guidesUser guides Troubleshooting guidesTroubleshooting guides Press ReleasesPress Releases Project ProposalsProject Proposals Policies and ProceduresPolicies and Procedures

White PapersWhite Papers

Industry/Commercial white papersIndustry/Commercial white papers There are also Government white papers, There are also Government white papers,

mostly specifics regarding public policy.mostly specifics regarding public policy. Describe the features and benefits of Describe the features and benefits of

software, hardware, protocols, and so on.software, hardware, protocols, and so on. Purpose is typically persuasive – to Purpose is typically persuasive – to

encourage others to buy or use a given encourage others to buy or use a given product or service.product or service.

Often marketing tools, but not strictly Often marketing tools, but not strictly advertisements.advertisements.

As marketing tools, white papers often focus As marketing tools, white papers often focus on highlights while downplaying limitations, on highlights while downplaying limitations, failings, and general problem issues.failings, and general problem issues.

The technical writer, not the inventor or The technical writer, not the inventor or development team, ultimately decides the development team, ultimately decides the content. content. Give your technical writer thorough Give your technical writer thorough

information.information. For your own sake, keep track of what For your own sake, keep track of what

you’ve sent him or her.you’ve sent him or her.

Reference DocumentsReference Documents Used to provide detailed information.Used to provide detailed information.

Not designed for linear readingNot designed for linear reading Indexes and tables of content can be crucialIndexes and tables of content can be crucial Sections should stand on their ownSections should stand on their own

The usefulness of these documents can The usefulness of these documents can depend on the writer’s understanding of depend on the writer’s understanding of the subject.the subject. Help your writer understand the topic.Help your writer understand the topic. Work with your writer to verify that he or she Work with your writer to verify that he or she

has presented accurate, useful information.has presented accurate, useful information.

Training Manuals & User Training Manuals & User GuidesGuides

Does the writer have a consistent style Does the writer have a consistent style for such manuals? (Many companies for such manuals? (Many companies require this.)require this.) Read previous manuals.Read previous manuals. Provide information that fits this format.Provide information that fits this format.

How closely are you going to work How closely are you going to work with the writer?with the writer? Is this a one-time contact?Is this a one-time contact? Are you going to be in regular contact?Are you going to be in regular contact?

Make sure the technical writer Make sure the technical writer knows the process. (As much as knows the process. (As much as possible.)possible.) Teach the writer.Teach the writer. Quiz the writer to make sure he or she Quiz the writer to make sure he or she

understands.understands. Your notes may end up as an outline for Your notes may end up as an outline for

his or her project.his or her project.

Troubleshooting GuidesTroubleshooting Guides

Expect that end users will have Expect that end users will have different problems than you will.different problems than you will.

Work with Quality Assurance and Work with Quality Assurance and any technical support departments any technical support departments to find common, real-world to find common, real-world problems.problems.

Project ProposalsProject Proposals

You are selling your idea.You are selling your idea. A good project proposal can lead to A good project proposal can lead to

a successful career, or even a a successful career, or even a successful company.successful company.

Whoever writes it should:Whoever writes it should: A) Understand your idea.A) Understand your idea. B) Share your enthusiasm for it.B) Share your enthusiasm for it.

Press ReleasesPress Releases Sometimes repeated verbatim or near-Sometimes repeated verbatim or near-

verbatimverbatim Can work to your organization’s benefitCan work to your organization’s benefit

Outrageous claims may be questioned or Outrageous claims may be questioned or refutedrefuted ““World changing”World changing” ““Effortless”Effortless” ““Once in a lifetime opportunity”Once in a lifetime opportunity”

Smaller claims may be accepted at face Smaller claims may be accepted at face value, even if untrue or vaguevalue, even if untrue or vague ““Battery life of up to 17 hours”Battery life of up to 17 hours” ““Best gas mileage of any car in its class.”Best gas mileage of any car in its class.”

Press releases (cont.)Press releases (cont.)

Make sure the author understands Make sure the author understands the implications of publicly the implications of publicly announcing claims.announcing claims. Inaccurate or misleading claims can Inaccurate or misleading claims can

hurt your organization’s reputation.hurt your organization’s reputation. Timing can be crucial.Timing can be crucial.

Timing - The Osborne EffectTiming - The Osborne EffectOsborne Computer Corporation released the first portable Osborne Computer Corporation released the first portable computer in 1981.computer in 1981.

5-inch Screen, Weighed 25 pounds.5-inch Screen, Weighed 25 pounds.In 1983, Adam Osborne announced the next generation of Osborne In 1983, Adam Osborne announced the next generation of Osborne months before its release.months before its release.This announcement killed sales of all current Osbornes, driving the This announcement killed sales of all current Osbornes, driving the company into bankruptcy.company into bankruptcy.

Press releases – the writing Press releases – the writing processprocess

Inverted pyramid structure – most important Inverted pyramid structure – most important information first.information first. ““The Pentium 5.0 processor, capable of speeds up to The Pentium 5.0 processor, capable of speeds up to

6.0ghz, was announced today by Intel CEO Paul 6.0ghz, was announced today by Intel CEO Paul Otellini.”Otellini.”

NotNot ““Today, Intel CEO Paul Otellini announced the Pentium Today, Intel CEO Paul Otellini announced the Pentium

5.0 processor, which is capable of speeds up to 6.0ghz.”5.0 processor, which is capable of speeds up to 6.0ghz.” Also – when information is cut, it’s cut from the bottom Also – when information is cut, it’s cut from the bottom

up.up.

Keep word count low:Keep word count low: Avoid unnecessary adjectives or wordy sentence Avoid unnecessary adjectives or wordy sentence

structure.structure.

Policies and ProceduresPolicies and Procedures

Precise language is important here.Precise language is important here. ““Remember: you can never add too Remember: you can never add too

much coolant to a nuclear reactor.”much coolant to a nuclear reactor.”

Sometimes, you don’t want a Sometimes, you don’t want a technical writer, you want a lawyer. technical writer, you want a lawyer. Or a doctor.Or a doctor.

Other Document TypesOther Document Types

Case StudiesCase Studies Test reportsTest reports Grant writingGrant writing Web ContentWeb Content Many othersMany others

Any questions?Any questions?