writing docs like a boss

35
Writing Docs Like a Boss By SiobhanPMcKeown Tuesday, 27 March 12

Upload: spmckeown

Post on 09-May-2015

1.355 views

Category:

Technology


3 download

TRANSCRIPT

Page 1: Writing Docs Like a Boss

Writing Docs Like a BossBy SiobhanPMcKeown

Tuesday, 27 March 12

Page 2: Writing Docs Like a Boss

Who the hell are you?Siobhan McKeown

Words for WPWordPress Documentation Specialist

Find my writing on:

Smashing MagazineWPMU.orgThe Quietus

Tuesday, 27 March 12

Page 3: Writing Docs Like a Boss

Who have I worked for?

Tuesday, 27 March 12

Page 4: Writing Docs Like a Boss

Why is documentation important?

Tuesday, 27 March 12

Page 5: Writing Docs Like a Boss

• 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

Page 6: Writing Docs Like a Boss

How do People Learn?

Tuesday, 27 March 12

Page 7: Writing Docs Like a Boss

Kinaesthetic

VisualKinaesthetic

Read/write

Auditory

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

Page 8: Writing Docs Like a Boss

• Preference for seeing

• Pictures & diagrams

• Screenshots with call outs

Visual

Tuesday, 27 March 12

Page 9: Writing Docs Like a Boss

• Listening

• Podcasts, audio

• Screencasts with strong narration

Auditory

Tuesday, 27 March 12

Page 10: Writing Docs Like a Boss

• Prefer to read text

• Documentation

• Most online docs will make these people happy!

Read/write

Tuesday, 27 March 12

Page 11: Writing Docs Like a Boss

• Actively doing

• Following steps that so they can achieve something

• Tutorials

Kinaesthetic

Tuesday, 27 March 12

Page 12: Writing Docs Like a Boss

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

Tuesday, 27 March 12

Page 13: Writing Docs Like a Boss

Types of Documentation

Tuesday, 27 March 12

Page 14: Writing Docs Like a Boss

Tutorials

Inline-docs

Screencasts

Hacks

Snippets

Tips

eBooksBooks

Reference

User GuidesInfographic

FAQ

GlossaryTooltips

TroubleshootingGuide

Tuesday, 27 March 12

Page 15: Writing Docs Like a Boss

Writing Docs Like a Boss

Tuesday, 27 March 12

Page 16: Writing Docs Like a Boss

• Who are you writing for?

• Developers? N00bs? Intermediate? End-Users?

• Aim low

Who is it for?

Tuesday, 27 March 12

Page 17: Writing Docs Like a Boss

What is it for?

• Learning to create something specific?

• General user guide?

• Reference?

Tuesday, 27 March 12

Page 18: Writing Docs Like a Boss

Find the right tone• Make people trust you

• Conversational

• Informative

• Knowledgable

Tuesday, 27 March 12

Page 19: Writing Docs Like a Boss

Tuesday, 27 March 12

Page 20: Writing Docs Like a Boss

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

Page 21: Writing Docs Like a Boss

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

Page 22: Writing Docs Like a Boss

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

Page 23: Writing Docs Like a Boss

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

Page 24: Writing Docs Like a Boss

• 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

Page 25: Writing Docs Like a Boss

Tuesday, 27 March 12

Page 26: Writing Docs Like a Boss

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

Page 27: Writing Docs Like a Boss

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

Page 28: Writing Docs Like a Boss

• Content Audit

• Front-end editor

• Edit Flow

• After the Deadline

• Document Revisions

Tuesday, 27 March 12

Page 29: Writing Docs Like a Boss

Content Audit http://wordpress.org/extend/plugins/content-audit/

Tuesday, 27 March 12

Page 30: Writing Docs Like a Boss

Front-end Editor http://wordpress.org/extend/plugins/front-end-editor/Tuesday, 27 March 12

Page 31: Writing Docs Like a Boss

Tuesday, 27 March 12

Page 32: Writing Docs Like a Boss

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

Page 34: Writing Docs Like a Boss

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

Tuesday, 27 March 12