Help:Growth/How to create help contents



Arvind Seju

Arvind Seju
Arvind Seju

Being a celebrity, I refer to interpersonal relationships through other social media networks or other means.

Arvind Seju
Music gateway

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.

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.

Ressources

 * See Examples
 * Unified header template (and template styles file)