Best Practices for Documenting Technical Procedures

32,850 views
32,345 views

Published on

Are you a technical expert who's been asked to document something? This presentation will give you basic principles for how to get started. (This presentation is written by me, but owned by cPanel, Inc. and used by permission.)

Published in: Business, Education
9 Comments
33 Likes
Statistics
Notes
No Downloads
Views
Total views
32,850
On SlideShare
0
From Embeds
0
Number of Embeds
564
Actions
Shares
0
Downloads
660
Comments
9
Likes
33
Embeds 0
No embeds

No notes for slide






















































  • Best Practices for Documenting Technical Procedures

    1. 1. Best Practices for Documenting Technical Procedures Melanie Seibert
    2. 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. 3. Documenting Procedures What about you? Are you a... ★ Technical support person? ★ Developer? ★ System Administrator? ★ Executive? ★ Something else?
    4. 4. Documenting Procedures If you’re here, you’re also a content producer.
    5. 5. Documenting Procedures The problem
    6. 6. Documenting Procedures The problem Expert (you)
    7. 7. Documenting Procedures The problem Expert Audience (you)
    8. 8. Documenting Procedures The problem information Expert Audience (you)
    9. 9. Documenting Procedures The problem needs to get here information Expert Audience (you)
    10. 10. Documenting Procedures Documentation! Expert Audience (you)
    11. 11. Documenting Procedures Expert Expert (you) (you)
    12. 12. Documenting Procedures How? 1. Plan. 2. Write. 3. Revise. 4. Edit. 5. Publish.
    13. 13. Documenting Procedures 1. Plan.
    14. 14. Documenting Procedures What do I want to say?
    15. 15. Documenting Procedures What do I want to say?
    16. 16. Documenting Procedures
    17. 17. Documenting Procedures Who is my audience?
    18. 18. Documenting Procedures Who is my audience? What do they need?
    19. 19. Documenting Procedures Who is my audience? What do they know? What do they need?
    20. 20. Documenting Procedures Who is my audience? What do they know? What do they need? How will they be looking for the information?
    21. 21. Documenting Procedures
    22. 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. 23. Documenting Procedures So... ★ Start at the beginning. ★ Listen and learn what your audience wants to know. ★ Make it about them, not you.
    24. 24. Documenting Procedures
    25. 25. Documenting Procedures This results in:
    26. 26. Documenting Procedures This results in:
    27. 27. Documenting Procedures
    28. 28. Documenting Procedures 2. Write
    29. 29. Documenting Procedures 2. Write badly.
    30. 30. Documenting Procedures
    31. 31. Documenting Procedures Everybody knows you should do things right the first time... right?
    32. 32. Documenting Procedures Everybody knows you should do things right the first time... right?
    33. 33. Documenting Procedures Do things badly the first time... just don’t leave them that way.
    34. 34. Documenting Procedures Why? ★ Being perfectionistic will get you “stuck.” ★ You don’t do anything wrong. Because you don’t do anything.
    35. 35. Documenting Procedures In writing, anything is better than nothing. So, write a terrible first draft.
    36. 36. Documenting Procedures 3. Revise.
    37. 37. Documenting Procedures This is where it gets good. Do not skip this step.
    38. 38. Documenting Procedures
    39. 39. Documenting Procedures
    40. 40. Documenting Procedures Create a logical flow. ★ Think like your reader. ★ Question and answer format often works well.
    41. 41. Documenting Procedures Be concise. ★ Don’t waste your readers’ time. ★ Be ruthless.
    42. 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. 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
    44. 44. Documenting Procedures Example:
    45. 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. 46. Documenting Procedures Why it works: ★ It’s easier to scan. ★ It’s approachable. ★ It’s understandable. ★ It’s friendly.
    47. 47. Documenting Procedures Another example:
    48. 48. Documenting Procedures Another example:
    49. 49. Documenting Procedures Another example:
    50. 50. Documenting Procedures What the writer did: ★ Used a table to format details. ★ Used bullets. ★ Used tabs to display categories of information.
    51. 51. Documenting Procedures Why it works: ★ It’s easy to scan. ★ The information is organized logically.
    52. 52. Documenting Procedures 4. Edit.
    53. 53. Documenting Procedures ★ Have someone proof your document before publishing.
    54. 54. Documenting Procedures huffingtonpost.com
    55. 55. Documenting Procedures huffingtonpost.com huffingtonpost.com
    56. 56. Documenting Procedures huffingtonpost.com huffingtonpost.com typobuddy.com
    57. 57. Documenting Procedures ★ Test it: watch someone “use” your document and listen to their thoughts.
    58. 58. Documenting Procedures 5. Publish.
    59. 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. 60. Documenting Procedures You’re not done Write Revise Plan Edit Publish
    61. 61. Documenting Procedures You’re not done never :) Write Revise Plan Edit Publish
    62. 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. 63. Documenting Procedures Resources: ★ Yahoo! Style Guide ★ Don’t Make Me Think by Steve Krug ★ Letting Go of the Words by Ginny Redish
    64. 64. Documenting Procedures Thanks!

    ×