{% 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 %}
{{ super() }} {% endblock content %} {% block main %}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.
In general you should try and follow the material design style guide.
General formatting guidelines that are applicable to all types of help text:
\n
in the help text.+
).help="Multi-line help text should "
"all have the same level of indentation."
help="You should break long "
"strings after a whitespace,\n"
"not before."
help="When using multiple sentences. "
"Code reviews will be easier like this."
Use: | "The last date when the MODEL-NAME can be used." |
Avoid: | "Prevent usage after this date." |
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." |
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: