Writing Docs Like a Boss

Writing Docs Like a Boss By SiobhanPMcKeownTuesday, 27 March 12

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

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 • Demonstrate pride in your code • Teach end-users about your product • Save on support forum requestTuesday, 27 March 12

How do People Learn?Tuesday, 27 March 12

K Visual Kinaesthetic Auditory Read/write h"p://www.vark-‐learn.com/Tuesday, 27 March 12

Visual • Preference for seeing • Pictures & diagrams • Screenshots with call outsTuesday, 27 March 12

Auditory • Listening • Podcasts, audio • Screencasts with strong narrationTuesday, 27 March 12

Read/write • Prefer to read text • Documentation • Most online docs will make these people happy!Tuesday, 27 March 12

Kinaesthetic • Actively doing • Following steps that so they can achieve something • TutorialsTuesday, 27 March 12

People learn in lots of different ways. Make your docs appeal to all of them.Tuesday, 27 March 12

Types of DocumentationTuesday, 27 March 12

Glossary Hacks Tutorials Tooltips Screencasts Snippets FAQ Inline-docs Tips Reference User Guides Infographic Troubleshooting Guide Books eBooksTuesday, 27 March 12

Writing Docs Like a BossTuesday, 27 March 12

Who is it for? • Who are you writing for? • Developers? N00bs? Intermediate? End-Users? • Aim lowTuesday, 27 March 12

What is it for? • Learning to create something specific? • General user guide? • Reference?Tuesday, 27 March 12

Find the right tone • Make people trust you • Conversational • Informative • KnowledgableTuesday, 27 March 12

Tuesday, 27 March 12

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

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

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

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

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

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

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

• Content Audit • Front-end editor • Edit Flow • After the Deadline • Document RevisionsTuesday, 27 March 12

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

Edit Flow http://wordpress.org/extend/plugins/edit-ﬂow/ h"p://wpcandy.com/teaches/how-‐to-‐manage-‐a-‐proper-‐mul9-‐author-‐wordpress-‐blogTuesday, 27 March 12

http://wordpress.org/extend/plugins/after-the-deadline/ After the Deadline http://afterthedeadline.comTuesday, 27 March 12

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 siobhan.mckeown@gmail.comTuesday, 27 March 12

http://2012.netherlands.wordcamp.org	9
https://abs.twimg.com	3
https://twimg0-a.akamaihd.net	1
http://translate.googleusercontent.com	1

Writing Docs Like a Boss

by spmckeown

Accessibility

Categories

Upload Details

Usage Rights

4 Embeds 14

Statistics

Writing Docs Like a Boss Presentation Transcript