Tech Writing for Techies A Primer By Ray Kim

About me... Blog: http://pianorayk.wordpress.com LinkedIn: https://www.linkedin.com/in/pianorayk Working in technology since 1989: Computer operator , instructor , technical writer , analyst , webmaster , developer Member of CASSUG (Albany SQL user group) and Albany UX/UI user group BS in computer science, Syracuse University (LET’S GO ORANGE!!!) MS in technical communication, Rensselaer Polytechnic Institute (GO RED!!!) Interests: My wife (Lianne) and two cats (Bernard, Nutmeg) Playing music (four different instruments, member of KKΨ band fraternity) Sports: Syracuse football and basketball, RPI ice hockey, NY Yankees, fantasy football, CrossFit

About this presentation This is NOT a technology-specific presentation Most of this material is based on personal experience I don’t like to lecture – I prefer to discuss issues and act as a facilitator Please ask questions! Feel free to engage!

About this presentation This presentation is NOT about layout and design, writing style, or grammar (although it helps!) Rather, we’ll discuss the following: What is technical writing? Why is it important? Why is tech writing marginalized? How can we improve the process?

Let’s start with a show of hands… Raise your hand if you’ve experienced the following: Frustration because a task was not documented Work stopped after the only person who knew something left Lost customers who were frustrated with your documentation Repeated a mistake, made a mistake, or missed a step in a task Bugs took too long to resolve because code wasn’t documented Someone made a mistake because (s)he “didn’t get the memo” Reinvented the wheel because instructions weren’t written down Came up with a great idea, and forgot all about it Wasted time and/or money because of any of the above

Technical writing – what people think it is Some people seem to think it’s ONLY about writing instruction manuals Writing instructions is not as easy as you think! Case in point: The Tie Demonstration Many people take documentation for granted NO RESPECT! However . . .

. . . it’s not just about writing manuals Technical writing comes in different shapes and sizes.

Technical writing – what is it? Source: http://grammar.yourdictionary.com/word-definitions/definition-of-technical-writing.html “…writing about a particular subject that requires direction, instruction, or explanation. This style of writing has a very different purpose…than other writing styles such as creative writing, academic writing or business writing.”

Why is tech writing important?

Why is tech writing important? Products become meaningless at best and dangerous at worst Retain critical information, instructions, and data Without documentation, we are constantly reinventing the wheel! Better understanding of subject matter Train employees, customers, and clients Business retention Do you lose business because of poor service or support? ROI in time and financial savings Security Many other reasons!

Why is tech writing important? Jeff Moden, via SQLServerCentral.com In a company where no code was documented, it took an average of two days to find and research a major proc that needed to be upgraded New rule: if you touch the code, you must also document the code After about a year… Research required dropped from 2 days to somewhere between 20 minutes and 2 hours Amount of code sent back by QA went from an average of two returns to nearly zero

Effects of bad documentation Bad documentation can result in . . . Bad reflection of your business or organization, especially with customers and clients Misleading or incorrect instructions or information Wasted time and effort Security breaches Legal issues Mistakes!!!

Think bad documentation doesn’t matter??? Coleco lost $35 million in a single quarter–and eventually went out of business–when customers purchased its computers, found the instruction manuals unreadable, and returned their computers. An oil company spent hundreds of thousands of dollars developing a pesticide, only to find that one of their technicians had worked out the formula five years earlier. The report was so poorly written that no one finished reading it. A nuclear plant supervisor ordered “ten foot long lengths” of radioactive material. Instead of getting ten-foot lengths, they received ten one-foot lengths, at a cost so great it was classified. Prof. Dorothy Winsor showed “a history of miscommunication” to be one of the root causes of the Challenger disaster in 1986. Sources: http://www.impact-information.com/impactinfo/costs.htm Egan, Michael. “Total Quality Business Writing” The Journal for Quality and Participation October/November 1995

So why are techies averse to documentation? Honestly, I don’t know, but here’s what I think . . .

“Cuz eye dont rite two gud” “It’s too hard!” “I’ve never been good at organization.” “We don’t need it!” “There’s too much to write!” “I have more important things to do.” “It’s BORING!!!” “I just hate it.” “Nobody does print anymore, so who cares?” “I just don’t have the time!” “It just takes too long!” “These people are just IT guys like me. So they don’t need good documents.” “It’s not a priority.” “I don’t know how.” “I’m not creative.” “I’m no good at it.” “I have too many other things to do!” “It’s obvious! Why do we need to write it down?” “It’s a waste of time!”

The documentation process Software is designed, written, tested, edited, vetted, and released. Like software, documentation has a development life cycle No difference between software and documentation production processes Why isn’t documentation treated the same way? Need to have a plan Understand the target audience Know the document’s purpose Have document specifications Your document is a product Be open to feedback

How can we make this process better? In other words, how can we make this less painful, especially for those who aren’t writers? To help answer this, let’s break this into two categories: informal vs. formal tech writing Informal Formal Internal environments ONLY!!! Clients/customers should NEVER see this!!! Can be used in either internal or external environments Design, good writing style, and grammar are not as important Design, good writing style, and grammar are CRITICALLY important!!! Should be well-organized MUST be well-organized!!! Can be done “on the fly” MUST have a plan!!! Can be more loose, free, and fun (within reason) Needs to be more…well… FORMAL

How “non-writers” can contribute to documentation Comment code “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” – Martin Fowler Write notes and other “informal” documents Contribute to an internal document source Departmental notebook Intranet SharePoint Wiki Be a subject matter expert (SME)

Some tips for improving your documentation Sometimes, low tech is a good place to start Start small and simple Use active, not passive, voice Passive: “The entire house was painted by Tom.” Active: “Tom painted the entire house.”

Some tips for improving your documentation Use proper spelling, grammar, and punctuation (* Okay, I lied; I do talk about grammar and writing style) Use illustrations and examples However, be smart about them. There IS a wrong way to use them! Don’t just arbitrarily throw in illustrations! Always remember the KISS principle!!! Remember: READING IS WORK!!! The less you have to make someone work, the better! If your reader can’t understand or utilize your document quickly and easily, it has failed. Test your document

Some tips for improving your documentation Scratch notes are NOT documentation Data : Information :: Notes : Documentation Make sure colleagues understand what you write Internal documents don’t need to be perfect, but they DO need to be UNDERSTOOD. Did I mention that READING IS WORK?!?!?!?!? Have a professional write or review all outward, customer, or client-facing documents Bad documentation can be dangerously misleading, and it makes you look BAD ALWAYS have someone check your work!

Some tips for improving your documentation Write, then rewrite “The secret to life is editing. Write that down. Now, cross it out.” – William Safire, SU commencement speech, 1990

What’d we just talk about? There’s more to technical writing than writing instruction manuals! Tech writing and documentation are critical business practices! However, despite being critical, people keep making excuses for not doing documentation. Anyone can contribute to documentation! Be careful – bad documentation can be – well – bad!

Some resources to check out “T-SQL's Hidden Support Feature” by Jen McCown – SQL Saturday presentation about using comments Society for Technical Communication (www.stc.org) – national technical communication association The Checklist Manifesto by Atul Gawande The Design of Everyday Things by Don Norman Your local library

Wrap-up Questions? Comments? Jokes? Wisecracks?

Thanks for listening, everyone! Check out my ‘blog: https://pianorayk.wordpress.com