Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Writing Docs Like a Boss               By SiobhanPMcKeownTuesday, 27 March 12
Who the hell are you?               Siobhan McKeown                       Words for WP                       WordPress Doc...
Who have I              worked for?Tuesday, 27 March 12
Why is documentation                       important?Tuesday, 27 March 12
• As an aid to future developers working on you product                 • So developers can do what they need to          ...
How do People Learn?Tuesday, 27 March 12
K                                    Visual   Kinaesthetic                                                 Auditory       ...
Visual              • Preference for seeing              • Pictures & diagrams              • Screenshots with call outsTu...
Auditory              • Listening              • Podcasts, audio              • Screencasts with strong narrationTuesday, ...
Read/write              • Prefer to read text              • Documentation              • Most online docs will make these...
Kinaesthetic              • Actively doing              • Following steps that so they can achieve something              ...
People learn in lots of                       different ways.                       Make your docs appeal to all          ...
Types of DocumentationTuesday, 27 March 12
Glossary                                                   Hacks     Tutorials                       Tooltips             ...
Writing Docs Like a BossTuesday, 27 March 12
Who is it for?              • Who are you writing for?              • Developers? N00bs? Intermediate? End-Users?         ...
What is it for?                       •   Learning to create something specific?                       •   General user gu...
Find the right tone               •       Make people trust you               •       Conversational               •      ...
Tuesday, 27 March 12
Stick to the point               Don’t start talking about               something off-topic               Keep the messag...
Learning Curve                       •   Produce docs for people at all levels                       •   Use taxonomies to...
Update              • Documentation needs to be updated with your product              • Don’t assume that once it’s done ...
Style               write in second person - i.e.               “you need to create a page”               it’s not poetry ...
Formatting               • use bold and italics               • have call-outs for tips and info               • use order...
Tuesday, 27 March 12
Screenshots & Video                       •   When writing a tutorial screenshot everything                       •   Scre...
Proofread!               •       offer your wife/girlfriend/husband/partner/boyfriend/brother/sister/                     ...
• Content Audit                       • Front-end editor                       • Edit Flow                       • After t...
Content Audit        http://wordpress.org/extend/plugins/content-audit/Tuesday, 27 March 12
Front-end Editor     http://wordpress.org/extend/plugins/front-end-editor/Tuesday, 27 March 12
Tuesday, 27 March 12
Edit Flow                      http://wordpress.org/extend/plugins/edit-flow/  h"p://wpcandy.com/teaches/how-­‐to-­‐manage-...
http://wordpress.org/extend/plugins/after-the-deadline/    After the Deadline   http://afterthedeadline.comTuesday, 27 Mar...
WP Document Revisions                       http://wordpress.org/extend/plugins/wp-document-revisions/Tuesday, 27 March 12
Thanks for listening!           @SiobhanPMcKeown           http://wordsforwp.com           http://siobhanmckeown.com      ...
Upcoming SlideShare
Loading in …5
×

Writing Docs Like a Boss

1,877 views

Published on

Published in: Technology, Business
  • Be the first to comment

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

×