11 Creating online help

Designing online help is about linking from an app or site to the documentation site for it.

The usefulness of online help will depend upon:

a.How many elements in the source can have links to the documentation.
b.How many entry points the documentation site allows.

Source links

Visuals and functionality really define how links can be incorporated.

The link density in the source will depend upon:

a.How many link sites can be incorporated into the source.
b.Whether a link site does not disrupt the visuals or functionality of where it is placed.
c.If by global key activation, how much of the context can be used to define the link target.

Having too many links can overload a screen visually or bog down keyboard users with excessive tabbing. Use of online help is only likely to be used initially for understanding the app or system, and very occasionally after. These usage scenarios indicate that the online help would be better being a table with the names and descriptions of each screen element, and in a section that would be the target of a cover-all link. Different areas or functional groupings of a screen can go to their own help sections.

Target elements

△

Only certain Smallsite Design elements can be the target of links.

The target elements available are:

a.Articles and categories.
b.Procedure steps and substeps.
c.Sections and subsections.
d.Glossary entries, either in a Glossary page or a general article.

Mostly, the target will be an an article per app or site screen, with a section of it for each area or functional block. A table in that section will list all the controls or areas by name in one column and their description in the next. For an example, see Category.

URL format

△

The link URLs have the same format as any other Smallsite Design page.

The URL format typically is:
https://domain/art/a-article-id/locale/#section-id
where:

a.domain – domain name of the help site.
b.a-article-id – target article.
c.locale – locale of the required help text, such as ar-001.
d.#section-id – section or other element on the article's page.

A subsection would be addressed like: #section-id--subsection-id. Glossary entries can be up to three levels deep in an article. Always include the locale to allow visually checking links, especially during development.

Approach

△

The help site can be developed in parallel with or after the app or site that it helps.

The recommended approach is to build the structure of the help site with the target articles and their internal addressable elements, but leave the rest of the content until the app or owning site is complete. This allows the greatest flexibility to experiment with the help structure while having concrete URLs to use for links in the source, and not having to shuffle around or edit help content prematurely.

An app or site may have been designed with only languages and maybe script, but a locale needs to be provided for the help site. Either use a suitable locale that has a region that matches or is close to the location where the source is principally to be used, or end the locale in -001 and the help will use a locale it has that has the same language and script, else the same language, else its master locale. If there is no default locale for the source app or site, nominate one to be used as the master for the help, as it cannot be changed after installation.