Help Text Guidelines

Purpose

The help messages for fields, buttons and selection values, which are displayed as tooltips in the client, are very useful for new users who are discovering Tryton and existing users who need to refresh their memory.

These help messages are part of Tryton's documentation and are great because they are easily displayed to users, at the time and place where they need to see them. They are also close to the code, as they are defined in the help parameters to fields, which helps developers keep them up to date, and allows them to be shown in the user's language.

These guidelines provide some clear rules on how to write this help text, so it is kept consistent and accurate across the whole application.

The help text should answer the question:

What is this, or what is it for?

If it is obvious what it is for, or what it does, then it is often better not to add any help text.

General Style

In general you should try and follow the material design style guide.

Language

• The help text is always written in English, Tryton will automatically display it in the user's language if a translation for it is available.
• Write in complete sentences, starting with a capital letter and ending with a full stop.
• Try and write text that adds useful information in a clear, accurate and concise way. Normally help text will be no more that one or two lines long.

Formatting

General formatting guidelines that are applicable to all types of help text:

• Always use double quotes for help text. In Tryton double quotes are normally used for human readable text, and help text is designed to be read by humans.
• If you need to add a line break it can be done using \n in the help text.
• Multi-line strings are concatenated without needing an operator (+).
• Indent multi-line help text so it all has the same level of indentation:

  help="Multi-line help text should "
  "all have the same level of indentation."

• Break long strings after a whitespace character:

  help="You should break long "
  "strings after a whitespace,\n"
  "not before."

• Start each sentence on a new line:

  help="When using multiple sentences. "
  "Code reviews will be easier like this."

Buttons

• Help text for buttons should describe the action or impact of pressing the button.

Fields

• Avoid using this or that when referring to the field's value because the help text may be used when the value is not visible:

  Use:	"The last date when the MODEL-NAME can be used."
  Avoid:	"Prevent usage after this date."

• On selection fields don't refer to the selection's options, these may change depending on what modules are activated.
• Help text for fields should describe either what is contained in the field or what it is used for. Avoid using verbs for these:

  Use:	"Used to group stock moves together."
  Use:	"The moves that put the stock away into the storage area."
  Avoid:	"Edit where to store the goods."

Standard Help Text

Fields

Some fields implement general functionality and are used in many different places in the same way. To keep things consistent use one of the standard help text values for these:

Name (name):

This should be pretty obvious and so no help text is normally required.

Name (rec_name):

The main identifier for the MODEL-NAME.

Parent:

Used to add structure above the MODEL-NAME.

Children:

Used to add structure below the MODEL-NAME.

Number:

The main identifier for the MODEL-NAME.

Code:

The internal identifier for the MODEL-NAME.

Reference:

The external identifier for the MODEL-NAME.

Origin:

The source of the MODEL-NAME.

Company:

The company that the MODEL-NAME is associated with.

State:

The current state of the MODEL-NAME.