Online Help Style Guide

The style sheet standard for Koha is written to create uniformity and to standardize the online help screens for Koha.

For every screen in the Koha intranet there is a help link. Clicking on this link will bring up help for that function. If you haven't seen the online help before, try going to the LibLime Online Demo. (← editor note: needs link)

Please remember the intended audience for the help page. For example, the help messages in the Search section (OPAC) should be written so that patrons or lay persons can easily understand the answers. On the other hand, help messages in the Circulation area should be written so that staff members can easily follow the answers, and complete the related tasks.

The style should be easily understood, avoid overly technical terms or jargon, and be as short as possible. In general, the patron areas should be easily understood by an eighth grader, while staff areas should be understood by a high school graduate. When possible, begin statements with action verbs, such as: “Go to the details screen” or “Click on 'issues'”.

Documentation writers do not need to add icons to the documentation themselves. However, all icons to be used will be from the Tango Icons site. (URL: http://tango-project.org/tango_icon_gallery). The following icons will be: emblem-important () for IMPORTANT, dialog-information for INFORMATION, dialog-warning for WARNING. Icons will be in the 22 X 22 bit size. (← editor note: tango link is broken, emblem-important icon not found)

When asking the end user to type information into Koha, use quotes and end quotes to bookend the desired keystrokes.

A word about technical issues: Koha is designed to have one central help page for each major action. If one page is not enough or if it is more logical to break a topic into sub groups, then nest the data within the original help screen. No more than two nests should be used, to minimize the number of clicks for the user (the three click rule).

The help session shall be designed using the Socratic method, i.e., by asking and then answering questions. The questions will be in the following format:

Please use the following wiki syntax. If the page has only one question associated with it:

===== Q: What color is your parachute? =====

If there are multiple questions relevant to the page, but all questions have equal weight, use all H2 tags for questions.

If there is more than one question, but some questions are 'nested' then the format will be:

===== Q: What color is your parachute? =====

==== Q:  How long should lunch take? ====

(These are H3 tags nested within H2 tags, using the visual editor.)

Q: What color is your parachute? A: Black and Blue.

If your question is best answered as a series of ordered 'steps', then please use the visual editor to created a numbered, bulleted list.

Here is a sample: http://wiki.koha.org/doku.php?id=reserve.pl

Though a question and answer style can deal with most questions, there are times when information can be more easily conveyed through other means. Koha supports the following two procedures to identify information or actions that must, may, or are merely suggested. Please use H4 headings to identify such procedures.

If the Help information needs to illustrate a task or provide advice to the end user through an example, use the format: first the dialog-information icon, then the word “TIP:”, followed by the stated information, in normal text.

TIP: Use an asterisk to search for a wild card. “Lib*” will search for library, librarians, and even librarianship.

In cases where there is information that users should consider, but do not necessarily have to follow, the format will be: first the dialog-warning icon, then the word “IMPORTANT:”, and then the desired text.

IMPORTANT: Title searching limits your chances of finding a book; try using Key Word Searching instead.

We are using the Tango Project Icons wherever possible. http://tango-project.org/Tango_Icon_Gallery (← editor note: tango link is broken)

For the help screens, we are using the 22×22 Icons.