Writing Docs Like a Boss

1,470
-1

Published on

Published in: Technology, Business
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,470
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
9
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Writing Docs Like a Boss

  1. 1. Writing Docs Like a Boss By SiobhanPMcKeownTuesday, 27 March 12
  2. 2. Who the hell are you? Siobhan McKeown Words for WP WordPress Documentation Specialist Find my writing on: Smashing Magazine WPMU.org The QuietusTuesday, 27 March 12
  3. 3. Who have I worked for?Tuesday, 27 March 12
  4. 4. Why is documentation important?Tuesday, 27 March 12
  5. 5. • As an aid to future developers working on you product • So developers can do what they need to • Demonstrate pride in your code • Teach end-users about your product • Save on support forum requestTuesday, 27 March 12
  6. 6. How do People Learn?Tuesday, 27 March 12
  7. 7. K Visual Kinaesthetic Auditory Read/write h"p://www.vark-­‐learn.com/Tuesday, 27 March 12
  8. 8. Visual • Preference for seeing • Pictures & diagrams • Screenshots with call outsTuesday, 27 March 12
  9. 9. Auditory • Listening • Podcasts, audio • Screencasts with strong narrationTuesday, 27 March 12
  10. 10. Read/write • Prefer to read text • Documentation • Most online docs will make these people happy!Tuesday, 27 March 12
  11. 11. Kinaesthetic • Actively doing • Following steps that so they can achieve something • TutorialsTuesday, 27 March 12
  12. 12. People learn in lots of different ways. Make your docs appeal to all of them.Tuesday, 27 March 12
  13. 13. Types of DocumentationTuesday, 27 March 12
  14. 14. Glossary Hacks Tutorials Tooltips Screencasts Snippets FAQ Inline-docs Tips Reference User Guides Infographic Troubleshooting Guide Books eBooksTuesday, 27 March 12
  15. 15. Writing Docs Like a BossTuesday, 27 March 12
  16. 16. Who is it for? • Who are you writing for? • Developers? N00bs? Intermediate? End-Users? • Aim lowTuesday, 27 March 12
  17. 17. What is it for? • Learning to create something specific? • General user guide? • Reference?Tuesday, 27 March 12
  18. 18. Find the right tone • Make people trust you • Conversational • Informative • KnowledgableTuesday, 27 March 12
  19. 19. Tuesday, 27 March 12
  20. 20. Stick to the point Don’t start talking about something off-topic Keep the message of your tutorial or guide clear Make sure your reader comes away with the message you need them toTuesday, 27 March 12
  21. 21. Learning Curve • Produce docs for people at all levels • Use taxonomies to categorise your docs properly • Use navigation to properly guide users through your docsTuesday, 27 March 12
  22. 22. Update • Documentation needs to be updated with your product • Don’t assume that once it’s done it’s done - it’s never done! • Use Content Audit or Edit Flow for keeping track of documentsTuesday, 27 March 12
  23. 23. Style write in second person - i.e. “you need to create a page” it’s not poetry - it’s documentation only say what you have toTuesday, 27 March 12
  24. 24. Formatting • use bold and italics • have call-outs for tips and info • use ordered and unordered lists • use headings • save time by writing in HTMLTuesday, 27 March 12
  25. 25. Tuesday, 27 March 12
  26. 26. Screenshots & Video • When writing a tutorial screenshot everything • Screenshots help visual learners follow your tutorial • Use screencasts to help visual and auditory learnersTuesday, 27 March 12
  27. 27. Proofread! • offer your wife/girlfriend/husband/partner/boyfriend/brother/sister/ girlfriend/best-friend/aunt/uncle/cousin/next-door-neighbour/mother-in-law/ business partner/secretary/postman/doctor/landlord cake to proofread for you • a fresh pair of eyes will see things that you will missTuesday, 27 March 12
  28. 28. • Content Audit • Front-end editor • Edit Flow • After the Deadline • Document RevisionsTuesday, 27 March 12
  29. 29. Content Audit http://wordpress.org/extend/plugins/content-audit/Tuesday, 27 March 12
  30. 30. Front-end Editor http://wordpress.org/extend/plugins/front-end-editor/Tuesday, 27 March 12
  31. 31. Tuesday, 27 March 12
  32. 32. Edit Flow http://wordpress.org/extend/plugins/edit-flow/ h"p://wpcandy.com/teaches/how-­‐to-­‐manage-­‐a-­‐proper-­‐mul9-­‐author-­‐wordpress-­‐blogTuesday, 27 March 12
  33. 33. http://wordpress.org/extend/plugins/after-the-deadline/ After the Deadline http://afterthedeadline.comTuesday, 27 March 12
  34. 34. WP Document Revisions http://wordpress.org/extend/plugins/wp-document-revisions/Tuesday, 27 March 12
  35. 35. Thanks for listening! @SiobhanPMcKeown http://wordsforwp.com http://siobhanmckeown.com siobhan.mckeown@gmail.comTuesday, 27 March 12
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×