Help:Growth/How to create help contents

Tracked in Phabricator
Task T211734

The following guide is intended to help experienced users on Wikimedia wikis build good help pages for new users.

Context

The Growth help panel project displays five links that goes to relevant help resources. This shows the need of good help pages. That is why this page exists.

The following best practices have been written after a comparative review of several help pages and help contents.

Since the Growth team's mandate is to work with mid-sized Wikipedias, the following is written accordingly. However, this page can be considered to be a universal resource, applicable to all wikis.

Structure of a help page

An help page consists of three things:

the content of the page, that covers the help text and anything that is requested to help readers to achieve their task. It 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 - how the content is displayed to the user,
the interactivity of the page, which leads readers to access to the contents and to more information.

Content of the page

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. Repetitions should be avoided as much as possible.

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

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

Context and pre-requested are summarized. Like on a Wikipedia article, there is no need to recall the entire context on which the help page is used. For instance, there is no need to detail what is a copyright violation on a page about inserting Quotes. However, since it is an important point to recall, it is vital to summarize it, and provide the appropriate links to it, for further readings.

Advanced content is 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 best practices. On wikis, help pages can be protected so that only users with a certain number of edits can edit them.

Illustrations

Images are used for examples. They are help users understand the actions they are to take. Illustrations can static; or 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.

Design of the page

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.

Alternative editing interfaces ("editors")

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

When different editing interfaces are available, examples should be provided for each.

This can be done in several ways:

Tabs that provide the relevant information for each editor (which requires a technical twist to work)
Separate pages that are linked together (with the risk that people will not identify the help content that matches their use case)
Different sections in the same help page (this is the most confusing option for people)

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.