![When WordPress updates, it automatically installs a .maintenance file. Following upgrade, you may receive a message that says "Briefly
unavailable 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 Happens
If 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 Devs
browser 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 McKeown
won't 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 Working
If you are experiencing 404 errors with pretty [[Using_Permalinks|permalinks] and a white screen when you upload images,mod_rewrite
may 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. It's 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 server
move.
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 On
RewriteBase /
RewriteRule ^index.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d](https://image.slidesharecdn.com/presentation-120609142532-phpapp01/85/killer-docs-for-killer-devs-1-320.jpg)
Recommended
More Related Content
What's hot
What's hot (20)
Viewers also liked
Viewers also liked (7)
Similar to Killer Docs for Killer Devs
Similar to Killer Docs for Killer Devs (20)
Recently uploaded
Recently uploaded (20)
Killer Docs for Killer Devs
- 1. When WordPress updates, it automatically installs a .maintenance file. Following upgrade, you may receive a message that says "Briefly unavailable 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 Happens If 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 Devs browser 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 McKeown won't 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 Working If you are experiencing 404 errors with pretty [[Using_Permalinks|permalinks] and a white screen when you upload images,mod_rewrite may 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. It's 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 server move. 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 On RewriteBase / RewriteRule ^index.php$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d
- 2. Siobhan McKeown WordPress Documentation & Content Specialist
- 4. “Lack of documentation. No matter how wonderful your library is and how intelligent its design, if you’re the only one who understands it, it doesn’t do any good. Documentation means not just autogenerated API references, but also annotated examples and in-depth tutorials. You need all three to make sure your library can be easily adopted.” Nicholas C. Zakas, software engineer, front-end consultant, author
- 5. Who are you writing your documentation for?
- 6. 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
- 7. How do people learn?
- 8. Visual Kinesthetic Auditory Read/write http://www.vark-learn.com/
- 9. Visual Learning 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 ■ flow charts & graphs ■ Flow charts ■ highlighted text, different colors, underlining ■ Highlights and bold ■ using symbols and white space ■ Graphics ■ Screencast like SEOMoz's Whiteboard Friday, which focuses on a person in front of a whiteboard. Recommended documentation types: in-depth tutorials, screencasts, graphics, infographics
- 10. Auditory Learning 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 people Recommended documentation types: tutorials, screencasts, podcasts, webinars
- 11. Read/Write Learning 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
- 12. Kinesthetic Learning 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 field 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 papers Recommended documentation types: practical tutorials, tips and hacks, use cases
- 13. Multimodal Around 60% of the population have 2 or more learning preferences e.g. Visual/Auditory, Read/Write/Kinesthetic adapt learning preferences to those around them
- 14. People learn in different ways; make sure your documentation is useful to everyone.
- 15. “We've been known to tell a developer "If it isn't documented, it doesn't exist." [...] Not only does it have to be doc'd, 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
- 16. Writing Your Killer Docs
- 17. 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.
- 18. 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
- 19. Stage 2: Writing End Middle Beginning
- 20. 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 you're going to do ■ tell the reader how you're going to do it ■ if you're writing a practical tutorial, demonstrate what the reader will achieve at the end
- 21. 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 ■ definitions and references ■ important pieces of information that I don't 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 you're writing your docs in WordPress, a popular plugin is Syntax Highlighter Reloaded.
- 22. Tutorial Example: Installing the BuddyPress Plugin 1. Download BuddyPress & Unzip Navigate to the WordPress plugin repository and download BuddyPress. Unzip to a folder that you can easily find on your computer, 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 do not 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, locate the unzipped BuddyPress folder. Drag and drop the folder to your remote website. 3. Activate the Plugin Log in to WordPress. Navigate to Plugins. Locate the BuddyPress plugin and click the activate link.
- 23. 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
- 24. 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?
- 25. Stage 3: Test, Revise, Update > Revise ■ If you have tested, incorporate any changes ■ Get rid of any wordiness. For example: "Now it's 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
- 26. 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.
- 27. 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.
- 28. 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
- 29. 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/
- 30. Thanks for Listening! Questions? @SiobhanPMcKeown http://wordsforwp.com Slides by Slidefix - http://slidefix.com
Editor's Notes
- \n
- My name is Siobhan McKeown\nWordPress documentation specialist. \nmeans I write docs for lots of different WordPress people and companies.\nWrite blog posts, articles, make screencasts, work on UI text, web content, press releases, but favourite thing is to write docs, which is what I&#x2019;m going to talk about today.\n
- Clients\nRecently reworked all the user docs for ManageWP and am currently doing screencasts for them\nWritten docs for Event Espresso\nInfinity @ Presscrew\nCurrently working with Piwik - OS web analytics\n
- When asked why good Javascript libraries fail, the author (and developer?) Nicholas C Zakas said:\n\nFor me, the key phrase is here: &#x201C;if you&#x2019;re the only one who understands it.&#x201D; \nAsked to work on Infinity, the only people who really understood how to use it were Bowe and Marshall. But, as the developers, their immediate proximity to Infinity made it difficult for them to write about it in a way that other people would understand. \nOther thing to take from this quote - &#x201C;all three to make sure your library can easily be adopted.&#x201D; See how that works in a WordPress context.\n
- Two broad groups - Developer and End User\nWho writes developer docs?\nWho writes end user docs?\nWho jumbles them both up together?\n\n
- A complete documentation project will contain many different types of documentation\n
- Going to take a little divergence into some learning theory.\n
- VARK - Visual, Auditory, Read/Write, Kinesethetic\n\nPeople take a 16 question questionnaire to discover what their learning preferences are.\n\nGoing to talk briefly about each of these\n
- On one side got the learning strategies that the VARK website recommends, and on the other how I think about reaching these people in my documentation.\n
- Auditory - hearing, listening, discussing. Much more difficult to reach through a screen which is really a visual medium.\n\nHowever...\n
- \n
- These guys are probably the most fun group to write docs for - they&#x2019;re about using all of their senses and getting hands-on\n
- If you&#x2019;re thinking that people can&#x2019;t be divided up that neatly - you&#x2019;re right.\n
- So often get asked to review a product&#x2019;s documentation and it is just straightforward (boring) text. The first thing I do is look at ways to bring variety to it, even just simple things like using bold and italics in the formatting, using headings, and adding screenshots.\n
- I love that.\n\nPeople will be excited - not about your documentation, but about your product.\nThis is definitely the lot of a documentation writer - no one cares what we do really (which is sad, because we&#x2019;re writers and we want people to love our writing). But as long as it&#x2019;s good then it&#x2019;s just a seamless part of the background. And when it&#x2019;s clear and useful, and helps people to actually learn, it gets people excited about your product.\n
- Focusing on end user docs\n
- Back to Infinity - I wrote a whole load of documentation and tutorials for Infinity, and then a few months later I talked to Bowe and he was all &#x201C;yeah, so we&#x2019;ve changed how loads of things are done so we&#x2019;re going to have to rewrite it.&#x201D;\n\nIn the first months of running Words for WP, this happened quite a lot. Now I tell developers to please have a features freeze in place. Without it, money and time is waisted with docs having to get written twice.\n\n2. Access the developer - so important. Need to be able to ask for help. Often the product has no documentation yet so everything needs to be extracted from the mind of the dev.\n\nDon&#x2019;t assume your writer is dumb!\n\nYour documentation project is a great time to be checking for usability issues and bugs. I have a tracker that I use in Google Docs to keep track of these things. I always come across bugs and usability issues (and UI spelling errors).\n
- Overall structure - if you&#x2019;re thinking about a complete doc project think about how you want your user to navigate through it. Do you want to go Beginner > Intermediate >Advanced or do you want to have discrete sections that cover different features - depends on the product.\nIndividual Article Structure - going to go into how to structure individual articles next\nAccess to resources - do you have everything you need? Will your user be able to get access to everything they need? Link to an FTP program, free text editor, etc.\nDoc Type - Ask what type of documentation is most suited to what you are trying to achieve. Do you want to produce a user guide that someone can dip into for what they need? Is a step-by-step tutorial more suitable? Would a screencast help? \nA complete documentation project is likely to contain many different types of documentation.\n\nThink about the level of your novice user. This is who you should be aiming for in your docs. A more advanced person will be able to extract what they need, whereas you still have yourself covered for novices. After all, they are probably going to be more of a hassle on your support forums.\n\nAnticipate user questions - with your novice in mind, anticipate what their questions will be and make sure you incorporate the answers into your docs. \n\nWP Admin Screens - you can integrate using the contextual help menus - have a link to a tutorial for that at the end.\n\nFigure out what your message is - this is really really important. Each piece of documentation should have a purpose, and a message, and your user should come away with that message, whether it&#x2019;s &#x201C;how to set up my eCommerce plugin&#x201D; or &#x201C;integrating Google Maps with my event management&#x201D;. Good docs are streamlined, to the point, and not full of fluff.\n\nWould be amazed how many things I&#x2019;ve come across which try to pack so many messages into one place that it&#x2019;s hard for an end user to know what to do.\n
- Every good story has a beginning, a middle and an end.\n
- introduce your reader to what you&#x2019;re going to do: eg. This tutorial with walk you through how to enqueue styles with an Infinity configuration file. or &#x201C;in this user guide, learn more about the different security settings for ManageWP.\n\nHow you&#x2019;re going to do it - not always relevant but if you&#x2019;re introducing a tutorial it&#x2019;s helpful to say something like &#x201C;in the next 7 steps, I&#x2019;ll walk you through blah blah blah&#x201D;\n- demo of what is achieved - screenshot, link to a demo, screencast.\n\n\n
- User guide - discrete sections. So, if you&#x2019;re writing a guide to payment gateways for your ecommerce plugin, break it up into PayPal, PayPal Pro, Authorize.Net etc etc\nTutorials - see next slide\nCall outs are really helpful as they alert people who are scanning text to things that are either important or outside the normal flow.\nScreenshots - I am screenshot liberal.\nScreencast - guy at wcnl asked if he could just use screencassts\nBe varied\nSyntax Highlighter - no doubt you all do. Have had a nightmare in the past with using syntax highlighters and then someone switches to the visual editor and everything goes kaboom.\n
- Imagine everyone here knows how to upload a plugin via FTP.\nDemonstrates the point.\nHeadings - can be clearly read by people with intermediate to advanced knowledge (go through stepsP\nBody text is detailed and useful for novices \nImages complement the text and could even be used on their own by someone scanning (go through images Download > upload > activate)\n\n
- Sum up what has been learned overall. That means if someone wants to return to a doc to get the essence of it, they can just check out the summing up at the end for a reminder.\nList the main points - get to see me doing that in action.\nAgain, a link to a demo or a screenshot of what the user should have achieved.\nList of resources or further reading - these could be on your site or elsewhere\nRelated tutorials or tutorials for taking it further.\nRelated posts plugins never work as well as I&#x2019;d like them to so I often do this manually.\nLink to support forums or feedback form.\n\nNever just end something - always show where the user can go next.\n\n
- Stage 3 is to Test, Revise, Update\n\nI ask a WP user to test complex pieces of documentation, especially tutorials that are code heavy or complicated. This ensures that the tutorial can be followed, that the steps and the code are correct.\n\nIf you&#x2019;re getting someone to read a user guide, think back to that main point or message that you came up with in your research phase. Ask questions to see if the user gets it.\n\nCollect their questions for use in an FAQ\n
- Incorporate changes.\nPare down language\n
- Documentation never ends.\nWordPress is updated\nYour product is updated\nbrowsers are updated\nAPIs change\neverything is constantly evolving.\nYou must be updating your documentation all of the time.\nGet a process in place to keep track of what needs to be updated. You could use a Google Spreadsheet, or a plugin such as content audit.\n
- \n
- \n
- \n
- Mention going to work on the codex on Sunday\n