{% set title = "Help Text Guidelines" %} {% set description = "Help text guidelines for Tryton" %} {% set keywords = ["development", "documentation", "guidelines", "help", "text"] %} {% set toc = [ ("Purpose", 'purpose', None), ("General Style", 'general-style', [ ("Language", 'language', None), ("Formatting", 'formatting', None), ]), ("Standard Help Text", 'standard-help-text', [ ("Fields", 'standard-fields', None), ]), ] %} {% extends "layout-toc.html" %} {% from "utils.html" import background with context %} {% block style %} {{ super() }} {{ background('banner-document') }} {% endblock %} {% block content %}

{{ title }}

{{ super() }} {% endblock content %} {% block main %}

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

Formatting

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

Buttons

Fields

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.
{% endblock main %}