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 headings 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, especially for new users
Don't make readers feel stupid, or 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.
Standardize format
Include short summaries
Include examples (sample code, etc)
Break down complex processes into steps
Use consistent terminology
Take the simplest route:
e.g. suggest Gadgets instead of editing user css/js, RefToolbar instead of hand-coding citations
Avoid overlinking
Make navigation clear and apparent
Chart the most common pathways and make them easy to find
Write a short and clear lede and/or {{nutshell}} summary
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
Use the appropriate namespace
Policies, guidelines, and processes firmly belong in the Wikipedia: namespace,
Instructions, how-to's, tutorials and explanations of MediaWiki features should be in the Help: namespace