Wikipedia:Help Project/Guidelines
 | This project page or section is in a state of significant expansion or restructuring. You are welcome to assist in its construction by editing it as well. If this project page has not been edited in several days, please remove this template. If you are the editor who added this template and you are actively editing, please be sure to replace this template with {{in use}} during the active editing session. Click on the link for template parameters to use.
This page was last edited by The wub (talk | contribs) 12 years ago. (Update timer) |
Help pages provide explanation, instruction, and practical guidance . This document lays out help page design principles to create useful, simple, accessible help pages that will answer editors' questions and solve their problems.
Focus on users and use cases
Speak to the reader about the problem they are trying to solve
- Use active, present tense language like "Adding references", "Customizing tables"...
- Use descriptive heading titles like "I want to...", "How do I...?"
- Help real people solve real problems. Don't give loads of background they don't need.
Encourage and reassure readers
Leave readers with more confidence and understanding than they started with
- A conversational style can help pages be more approachable and enjoyable to work with
- Don't make readers feel guilty for not having read all of the Help articles
Keep it simple
Focus on the most common paths and make them easily visible
- Keep sentences and paragraphs short. Sentences should be fewer than 25 words. Paragraphs should focus on only one topic.
- Include short summaries
- Include examples (sample code, etc)
- Break down complex processes into steps
- Use consistent terminology
- Prefer built-in functionality like Gadgets and RefToolbar to customized hacks with javascript and css
- Avoid overlinking
Make navigation clear and apparent
Chart the most common pathways and make them easily to find
- Write a short and clear lede/nutshell
- Note when there is a simpler overview--or a more technical help article--available
- Guide users through an obvious progression of where to go next
- Keep the namespaces separate
- Policies, guidelines, and processes firmly belong in the Wikipedia: namespace,
- Instructions, how-to's and tutorials should be in the Help: namespace
Help pages should be visually appealing
Entice users with clear design
- Break pages into sections and subsections
- Use bold and descriptive headers
- Illustrate articles with rich media
- Screenshots (high quality .png, not .jpeg)
- Screencasts (videos)
- Don't break accessibility
- Images should have alt text
- Tables should have sensible headings and captions where appropriate
- Wrap large blocks of code, examples, and rare cases in a collapse box
- Use templates such as {{notice}}, {{caution}} where appropriate
Target help pages to different levels of experience
Make overviews that address the most common problems with the most effective solutions
- Craft intro articles that are simple, short, and not overwhelming
- Link to terms that have been introduced before
- Link to the least complex technical page available
- Separate and minimize advanced and highly-specific use cases
External links
Other documentation style guides
- Mozilla Support
- Mozilla Developer Network
- GNOME
- Especially their "Golden Rules"
- Python
- Ubuntu
- Fedora