Help:Growth/How to create help contents

The following guide is created to help experienced users on Wikimedia wikis on how to built the best help pages for new users.

Context
The Growth help panel project displays 5 links that goes to relevant help resources. This surfaces the need of good help pages. This is why we have created this page.

The following best practices have been written after a comparative review of several help pages and help contents. These contents are all focusing on creating written contents (blog posts, wiki pages, code samples, etc.).

Since Growth team mandate is to work with mid-sized Wikipedias, the following contents are written accordingly. However, they've been thought as a universal resource, and they can be applied to other wikis.

Structure of a page
An help page is divided into 3 parts:


 * the content of the page, that covers the help text and anything that is requested to help readers to achieve their task. It both includes:
 * how to write the contents,
 * how to illustrate the contents with examples, images (screenshots, GIFs...), code citation, and more,
 * the design of the page, which is about how the content is displayed to the user,
 * the interactivity around the page, which leads readers to access to the contents and to more information.

Tone and writing
Help contents are short and focused: one title and a few sentences for a simple task, one sub-title and a few sentences for each step of a more complex workflow. Each point that needs to be explained is separated from the others by a title or a subtitle. Each section is focusing on one point.

Style of writing is friendly to encourage people to do the changes, but it remains succinct, without a profusion of greetings or jokes.

Step-by-steps are a key feature for help contents. They can be a simple list within a section, or numbered sections. They are sometimes more complex steps-by-steps (animated illustrations, drawings-based contents…).

Advanced contents are offered as additional resources (“see also”, “know more”...). They are not integrated in the help page itself, not even mentioned (no short paragraph about an advanced feature). This is for recommendations or guidances that are supposed to be under the Wikipedia: namespace.

Help contents are not editable by regular users. A set of trusted users should edit help pages, to be sure that the help contents follow the best practices defined. On wikis, help pages can be protected so that only users with a certain number of edits can edit them.

Illustrations
Images are used to provide examples. They are help to help users to understand the action they try to do. They can be GIFs, showing an action, or videos. Illustrative images, put on the page just for the purpose of having an image, are not really useful.

Icons are added in-text when they are used for the action being explained.

Specific designs
Help contents have a specific design. This design that makes it clear that Help pages are not a regular site content. Help pages on Wikipedia shouldn't have the same design as articles to avoid confusion.

Help pages have a limited width to increase readability.

A link to a place where to ask a question is provided. Users have sometimes the possibility to ask for a question at a separate place (chat, forum, etc.).

Mobile compatibility must be provided. Help pages must be universally readable.

Multiple editors
On our wikis, we have several ways to edit pages: the visual editor on desktop, the wikitext editor on desktop, the visual editor on mobile website, the wikitext editor on mobile website, and, as less used editors, wikitext editors on Apps and community wikitext editors. We encourage communities to push for the visual editor as the default experience.

So for a given task, if several devices or editors can be used by users, examples should be provided for each.

This can be solved by having either:


 * tabs that provide the relevant information for each editor (which requires to have a technical twist to work),
 * separated pages that are linked together (with the risk of people not identifying the help content that matches their case),
 * different sections in the same help page (the latter being the less clear option).

Interactivity of pages
A search field targeting Help is provided for a majority of services. It also means that every help contents are listed under the Help namespace.

Contents should be tiered. For instance, "how to insert an image" should be listed under a parent page about "inserting contents". Categories on wikis are too confusing to be used as a way to browse contents. They should be used only for maintenance purposes.

Advanced contents are offered as additional resources (“see also”, “know more”...). They are not detailed, just links with a very short label.


 * They are mostly at the end of a section, with a specific design to identify them. They can also be found at the end of the entire page.
 * They should be focusing on tangent topics. Example: if you are on a page about adding an image, you can add links to other ways to add other contents.

A feedback loop should be offered to know if the contents match the expectations from the user.