Tech Writing for Techies

1. Tech Writing for Techies A Primer By Ray Kim

2. About me... Blog:http://pianorayk.wordpress.com LinkedIn:https://www.linkedin.com/in/pianorayk 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 Working in technology since 1989: , analyst , webmaster , technical writer , developer Computer operator , instructor 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!!!)

3. 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!

4. 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?

5. 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

7. 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 . . .

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

9. 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.”

10. Why is tech writing important?

11. 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!

12. 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

13. 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!!!

14. Think bad documentation doesn’t matter??? • Colecolost $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

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

16. “It’s too hard!” “I’ve never been good at organization.” “Cuz eye dont rite two gud” “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 a waste of time!” “It’s obvious! Why do we need to write it down?”

17. 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

18. 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 • Can be used in either internal or external environments • Internal environments ONLY!!! Clients/customers should NEVER see this!!! • 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

19. 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)

20. 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.”

21. 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

22. 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 dangerouslymisleading, and it makes you look BAD • ALWAYS have someone check your work!

23. 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

24. 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!

25. 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 AtulGawande • The Design of Everyday Things by Don Norman • Your local library

26. Wrap-up • Questions? • Comments? • Jokes? • Wisecracks?

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