Writing Policy Review Process Rebecca Woosley Carol Franks Renee Boss KDE Literacy Consultants 1.
Writing Docs Like a Boss
-
Upload
spmckeown -
Category
Technology
-
view
1.355 -
download
3
Transcript of Writing Docs Like a Boss
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://[email protected]
Tuesday, 27 March 12