Best Practices for Documenting Technical Procedures
49 likes36,325 views
The document provides best practices for documenting technical procedures in 5 steps: 1) Plan by understanding your audience and their needs. 2) Write a first draft without perfectionism. 3) Revise by creating a logical flow, using concise language, and removing unnecessary information. 4) Edit by having others proofread. 5) Publish while considering the format and long-term maintenance. The key aspects are understanding the audience, writing concisely, revising for clarity, editing for errors, and planning for ongoing support of the documentation.
Best Practices for Documenting Technical Procedures
- 1. Best Practices for Documenting Technical Procedures Melanie Seibert
- 2. Documenting Procedures Hello. This is me: ★ BA & MA in English ★ 5 years as a copywriter (both print & web) ★ 3 years as a part-time freelancer/full-time mom ★ 3 years total as a tech writer (2 at cPanel) ★ Now Documentation Supervisor at cPanel ★ Interested in how content is developed, managed, understood, and used
- 3. Documenting Procedures What about you? Are you a... ★ Technical support person? ★ Developer? ★ System Administrator? ★ Executive? ★ Something else?
- 4. Documenting Procedures If you’re here, you’re also a content producer.
- 6. Documenting Procedures The problem Expert (you)
- 7. Documenting Procedures The problem Expert Audience (you)
- 8. Documenting Procedures The problem information Expert Audience (you)
- 9. Documenting Procedures The problem needs to get here information Expert Audience (you)
- 10. Documenting Procedures Documentation! Expert Audience (you)
- 11. Documenting Procedures Expert Expert (you) (you)
- 12. Documenting Procedures How? 1. Plan. 2. Write. 3. Revise. 4. Edit. 5. Publish.
- 14. Documenting Procedures What do I want to say?
- 15. Documenting Procedures What do I want to say?
- 17. Documenting Procedures Who is my audience?
- 18. Documenting Procedures Who is my audience? What do they need?
- 19. Documenting Procedures Who is my audience? What do they know? What do they need?
- 20. Documenting Procedures Who is my audience? What do they know? What do they need? How will they be looking for the information?
- 22. Documenting Procedures ★ We usually assume people know what we know. We almost never start at a level too basic. ★ We usually assume they want to know what we want to tell them. ★ Many times, what we want to tell them is mainly about us.
- 23. Documenting Procedures So... ★ Start at the beginning. ★ Listen and learn what your audience wants to know. ★ Make it about them, not you.
- 29. Documenting Procedures 2. Write badly.
- 31. Documenting Procedures Everybody knows you should do things right the first time... right?
- 32. Documenting Procedures Everybody knows you should do things right the first time... right?
- 33. Documenting Procedures Do things badly the first time... just don’t leave them that way.
- 34. Documenting Procedures Why? ★ Being perfectionistic will get you “stuck.” ★ You don’t do anything wrong. Because you don’t do anything.
- 35. Documenting Procedures In writing, anything is better than nothing. So, write a terrible first draft.
- 37. Documenting Procedures This is where it gets good. Do not skip this step.
- 40. Documenting Procedures Create a logical flow. ★ Think like your reader. ★ Question and answer format often works well.
- 41. Documenting Procedures Be concise. ★ Don’t waste your readers’ time. ★ Be ruthless.
- 42. Documenting Procedures “Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.” — Strunk & White, The Elements of Style
- 43. Documenting Procedures “Get rid of half the words on the page, then get rid of half of what’s left.” — Steve Krug, Don’t Make Me Think
- 45. Documenting Procedures What I did: ★ Formatted it as Q&A. ★ Used headings and bullets. ★ Defined basic terms. ★ Answered the most pressing questions first. ★ Removed unnecessary information.
- 46. Documenting Procedures Why it works: ★ It’s easier to scan. ★ It’s approachable. ★ It’s understandable. ★ It’s friendly.
- 50. Documenting Procedures What the writer did: ★ Used a table to format details. ★ Used bullets. ★ Used tabs to display categories of information.
- 51. Documenting Procedures Why it works: ★ It’s easy to scan. ★ The information is organized logically.
- 53. Documenting Procedures ★ Have someone proof your document before publishing.
- 55. Documenting Procedures huffingtonpost.com huffingtonpost.com
- 56. Documenting Procedures huffingtonpost.com huffingtonpost.com typobuddy.com
- 57. Documenting Procedures ★ Test it: watch someone “use” your document and listen to their thoughts.
- 59. Documenting Procedures Points to consider before publishing: ★ Who are your users? ★ Where will they look for info? ★ Do they want print? web? mobile?
- 60. Documenting Procedures You’re not done Write Revise Plan Edit Publish
- 61. Documenting Procedures You’re not done never :) Write Revise Plan Edit Publish
- 62. Documenting Procedures Points to consider after publishing: ★ Long-term maintenance: who will do it? ★ Conventions: consider starting a style guide. ★ Consider a site audit or inventory if you have lots of documentation.
- 63. Documenting Procedures Resources: ★ Yahoo! Style Guide ★ Don’t Make Me Think by Steve Krug ★ Letting Go of the Words by Ginny Redish
- 64. Documenting Procedures Thanks!