Killer Docs for Killer Devs

When WordPress updates, it automatically installs a .maintenance file. Following upgrade, you may receive a message that says "Brieflyunavailable for scheduled maintenance. Please check back in a minute." The maintenance file may not have been removed properly.To remove this message do the following: 1. Log in to your website using your FTP program 2. Delete the .maintenance file, which will be found in your site root.Read more about the maintenance mode issue.You Make Changes and Nothing HappensIf you are making changes to your website and you do not see the changes in your browser, you may need to clear your browser cache.Your browser stores information about the websites that you visit. This makes it faster to load websites when you visit them because the Killer Docs for Killer Devsbrowser just has to reload information already stored on your computer, rather than downloading it again.If you make a change to a website and the browser does not think it is significant, it will simply load the data from your cache, and you Siobhan McKeownwont see your changes. To fix the problem, simply empty your browser cache or close the tab and reopen the link.Pretty Permalinks 404 and Images not WorkingIf you are experiencing 404 errors with pretty [[Using_Permalinks|permalinks] and a white screen when you upload images,mod_rewritemay not be enabled in Apache by default. Mod_rewrite is an extension module of the Apache web server software which allows for"rewriting" of URLs on-the-fly. Its what you need to make pretty permalinks work.WordPress Multisite networks usually experience this but it can also occur on shared hosting providers or after a site migration or servermove.Reset your permalinks through Settings > Permalinks. If this does not work, you may have to edit the .htaccess file manually.# BEGIN WordPress<IfModule mod_rewrite.c>RewriteEngine OnRewriteBase /RewriteRule îndex.php$ - [L]RewriteCond %{REQUEST_FILENAME} !-fRewriteCond %{REQUEST_FILENAME} !-d

Siobhan McKeownWordPress Documentation & Content Specialist

Find My Writing

“Lack of documentation. No matter how wonderful your library is and howintelligent its design, if you’re the only one who understands it, it doesn’tdo any good. Documentation means not just autogenerated API references,but also annotated examples and in-depth tutorials. You need all three tomake sure your library can be easily adopted.” Nicholas C. Zakas, software engineer, front-end consultant, author

Who are you writing your documentation for?

Types of Documentation■ Reference ■ FAQs■ API Reference ■ Tooltips■ In-line documentation and ■ User guides comments ■ Troubleshooting guides■ List of requirements ■ Screencasts■ Glossary ■ Books/ebooks■ Architecture or design overview ■ Quick hacks & tips■ Tutorials ■ Infographics■ Manuals ■ Screencasts■ Readmes ■ Recording webinars■ WordPress help menus

How do people learn?

VisualKinesthetic Auditory Read/write http://www.vark-learn.com/

VisualLearning Strategies Incorporate in Docs■ presenters who use pictures or gestures ■ Call-outs draw attention to notes and tips■ pictures, posters and slides ■ Useful screenshots with arrows, highlights■ books with pictures and diagrams and writing■ ﬂow charts & graphs ■ Flow charts■ highlighted text, different colors, underlining ■ Highlights and bold■ using symbols and white space ■ Graphics ■ Screencast like SEOMozs Whiteboard Friday, which focuses on a person in front of a whiteboard.Recommended documentation types: in-depth tutorials, screencasts, graphics, infographics

AuditoryLearning Strategies Incorporate in Docs■ go to classes ■ podcasts■ get involved in discussions ■ screencasts with detailed narration■ explain ideas to other people ■ interesting, practical examples■ use a tape recorder ■ though not documentation, a chat room such■ engage with interesting examples as the WordPress IRC chat, is great for people■ describe things to someone else second-hand who like to discuss issues ■ same goes for support forums ■ same goes for screensharing on Skype ■ webinars are great auditory means for engaging peopleRecommended documentation types: tutorials, screencasts, podcasts, webinars

Read/WriteLearning Strategies Incorporate in Docs ■ use ordered and unordered lists■ lists ■ make use of the whole spectrum of headings■ headings tags■ dictionaries ■ include definitions in call-out boxes■ glossaries ■ link to definitions elsewhere■ definitions ■ write a user guide■ reading large piece of text ■ write a glossary (the glossary in the■ reading and writing essays WordPress Codex is a great example)■ manuals (computing, technical and ■ produce an ebook or manual laboratory)Recommended documentation types: tutorials, ebooks, manuals, glossaries, references

KinestheticLearning Strategies Incorporate in Docs ■ Tutorials in which the person can follow the■ using all your senses - sight, touch, taste, steps to produce something smell, hearing ■ In-depth use cases■ going on ﬁeld trips ■ links to practical examples■ practical examples of abstract principles ■ talk about real-life examples, rather than in■ using real life examples abstraction■ hands-on approaches ■ interactive learning tools such as■ trial and error Codecademy■ looking at collections of things - rock ■ short, practical tutorials such as those on types, plants, shells, grasses, case studies WPRecipes■ exhibits, samples, photographs ■ webinars that walk the participants through■ recipes - solutions to problems, previous doing something practical exam or test papersRecommended documentation types: practical tutorials, tips and hacks, use cases

MultimodalAround 60% of the population have 2 or more learning preferencese.g. Visual/Auditory, Read/Write/Kinestheticadapt learning preferences to those around them

People learn in different ways; make sure yourdocumentation is useful to everyone.

“Weve been known to tell a developer "If it isnt documented, it doesnt exist." [...] Not only does it have to be docd, but it has to be explained and taught and demonstrated. Do that, and people will be excited -- not about your documentation, but about your product.”Mike Pope, Technical Editor, Microsoft

Writing Your Killer Docs

Before you get started: 1. Make sure there is a features freeze. 2. If you aren’t the developer, make sure you have access to them. 3. Prepare for making notes of bugs and usability issues.

Stage 1: Research and Prepare• Plan: overall architecture• Plan: article structure• Access to resources• Decide on the appropriate doc type• Aim for the novice• Anticipate user questions• Integration with WordPress Administration Screens• Figure out your message

Stage 2: Writing End Middle Beginning

Stage 2: Writing > Beginning■ include a list of requirements - e.g. WordPress 3.3+■ provide a list of resources that a user will need to complete any practical sections - e.g. an FTP client or a Text editor■ introduce the reader to what youre going to do■ tell the reader how youre going to do it■ if youre writing a practical tutorial, demonstrate what the reader will achieve at the end

Stage 2: Writing > Middle■ Break the body of user guides up into self-contained sections which deal with one main topic.■ Tutorials should be split up into discrete steps.■ Use call-out boxes to highlight useful pieces of information. For example; ■ useful tips ■ deﬁnitions and references ■ important pieces of information that I dont want people who scan to miss ■ advanced tips for more experienced users■ use screenshots liberally.■ think about including a screencast.■ use varied media to include all learning preferences - Visual, Read/ Write, Kinesthetic, Aural.■ use a syntax highlighter to improve code readability. If youre writing your docs in WordPress, a popular plugin is Syntax Highlighter Reloaded.

Tutorial Example: Installing the BuddyPress Plugin1. Download BuddyPress & UnzipNavigate to the WordPress plugin repository and downloadBuddyPress. Unzip to a folder that you can easily ﬁnd on yourcomputer, to your Desktop, for example.2. Upload via FTP to wp-content/plugins/Open up your favorite FTP program (FileZilla, for example). Input your FTP login details. If you donot have these you will be able to get them from your web host.Once you are logged into your server, navigate to wp-content/plugins/. On your local server, locatethe unzipped BuddyPress folder. Drag and drop the folder to your remote website.3. Activate the PluginLog in to WordPress. Navigate to Plugins. Locate the BuddyPress pluginand click the activate link.

Stage 2: Writing > End■ Sum up large pieces of documentation.■ List the main points.■ Finish with a screenshot of what the user should have achieved, or a link to an example.■ List of resources or further reading■ List of tutorials for taking things further■ Include a link to your support forums or feedback form

Stage 3: Test, Revise, Update > Test• Ask a WordPress user to test complex pieces of documentation• Can they follow all the steps?• Are there any areas of confusion?• Is the tester understanding the main points that you want them to?

Stage 3: Test, Revise, Update >Revise■ If you have tested, incorporate any changes■ Get rid of any wordiness. For example: "Now its time for you to visit the WordPress Administration Screens" could be revised to "Visit the WordPress Administration Screens"■ Fix any typos and grammatical errors■ Add any links that you may have missed out

Stage 3: Test, Revise, Update >Update■ Updates happen in line with your own product being updated, and WordPress core updates■ Update screencasts and screenshots to reflect the current WordPress UI■ Update your documentation to reflect any feature or functionality changes■ Update your documentation to reflect updates that make use of new WordPress functionality■ Update your documentation based on user feedback■ Use a plugin like Content Audit to keep track of updates.

Practical Writing Tips■ Be clear, concise and engaging.■ Don’t try to get poetic or clever.■ Never assume that your user just knows something; it’s your job to tell them.■ Write in the second person; i.e. "when you have logged into WordPress you should navigate to the plugin admin screen".■ Stick to the point.■ Restrict yourself to one major point per paragraph.■ Use formatting and be consistent about it.■ Information should follow in a logical order.■ Write in the present tense.■ Find the right tone.■ Proofread.

Keep in Mind• Don’t let your product fail through lack of documentation• Your docs should get people excited about your product• People learn in different ways so have diverse doc types• Aim for the novice• Plan your architecture and structure• Keep your docs updated

Resources• PHPDocumentor http://phpdoc.org/• Pea.rs http://pea.rs• queryposts.com http://queryposts.com• Chip Bennett on Incorporating Contextual Help and Support http://upthemes.com/blog/2012/05/incorporating-contextual- help-and-support-into-wordpress-themes/• Content Audit WordPress Plugin http://wordpress.org/extend/plugins/content-audit/

Thanks for Listening! Questions? @SiobhanPMcKeownhttp://wordsforwp.comSlides by Slideﬁx - http://slideﬁx.com

http://wpmu.org	1407
http://nicewpthemes.blogspot.com	69
http://feeds.feedburner.com	7
http://wpdojo.net	7
http://127.0.0.1	2
http://top-wordpressthemes.blogspot.com	2
http://www.mefeedia.com	2
http://top-wordpressthemes.blogspot.de	1
http://tweetedtimes.com	1
http://nicewpthemes.blogspot.nl	1
http://www.hanrss.com	1
http://webcache.googleusercontent.com	1

Killer Docs for Killer Devs

by spmckeown on Jun 09, 2012

Accessibility

Categories

Upload Details

Usage Rights

12 Embeds 1,501

Statistics

Killer Docs for Killer Devs Presentation Transcript