Writing Docs Like a BossBy SiobhanPMcKeown

Tuesday, 27 March 12

Who the hell are you?Siobhan McKeown

Words for WPWordPress Documentation Specialist

Find my writing on:

Smashing MagazineWPMU.orgThe Quietus

Tuesday, 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 request

Tuesday, 27 March 12

How do People Learn?

Tuesday, 27 March 12

Kinaesthetic

VisualKinaesthetic

Read/write

Auditory

h"p://www.vark-­‐learn.com/Tuesday, 27 March 12

• Preference for seeing

• Pictures & diagrams

• Screenshots with call outs

Visual

Tuesday, 27 March 12

• Listening

• Podcasts, audio

• Screencasts with strong narration

Auditory

Tuesday, 27 March 12

• Prefer to read text

• Documentation

• Most online docs will make these people happy!

Read/write

Tuesday, 27 March 12

• Actively doing

• Following steps that so they can achieve something

• Tutorials

Kinaesthetic

Tuesday, 27 March 12

People learn in lots of different ways.Make your docs appeal to all of them.

Tuesday, 27 March 12

Types of Documentation

Tuesday, 27 March 12

Tutorials

Inline-docs

Screencasts

Hacks

Snippets

Tips

eBooksBooks

Reference

User GuidesInfographic

FAQ

GlossaryTooltips

TroubleshootingGuide

Tuesday, 27 March 12

Writing Docs Like a Boss

Tuesday, 27 March 12

• Who are you writing for?

• Developers? N00bs? Intermediate? End-Users?

• Aim low

Who is it for?

Tuesday, 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

• Knowledgable

Tuesday, 27 March 12

Tuesday, 27 March 12

Don’t start talking about something off-topicKeep the message of your tutorial or guide clearMake sure your reader comes away with the message you need them to

Stick to the point

Tuesday, 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 docs

Tuesday, 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 documents

Tuesday, 27 March 12

write in second person - i.e. “you need to create a page”it’s not poetry - it’s documentationonly say what you have to

Style

Tuesday, 27 March 12

• use bold and italics

• have call-outs for tips and info

• use ordered and unordered lists

• use headings

• save time by writing in HTML

Formatting

Tuesday, 27 March 12

Tuesday, 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 learners

Tuesday, 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 miss

Tuesday, 27 March 12

• Content Audit

• Front-end editor

• Edit Flow

• After the Deadline

• Document Revisions

Tuesday, 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

Tuesday, 27 March 12

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

After the Deadlinehttp://wordpress.org/extend/plugins/after-the-deadline/

http://afterthedeadline.com

Tuesday, 27 March 12

WP Document Revisionshttp://wordpress.org/extend/plugins/wp-document-revisions/

Tuesday, 27 March 12

Thanks for listening!@SiobhanPMcKeownhttp://wordsforwp.comhttp://siobhanmckeown.comsiobhan.mckeown@gmail.com

Tuesday, 27 March 12