How to write tooltips

Feature
1

Rationale

The help messages of fields and buttons, which are represented as tooltips in the client, are very useful for new users to discover the application and for old users to refresh their memory.
In some ways, they are better than documentation because they are at the place where the user needs them and they are very close to the code so developers keep them up to date.
But we need clear rules on how to write them, so they are consistent across the whole application and we must take care of possible extensions changing the behavior.

Proposal

Help text answers the question:

What is this field/button for?

The help text that answers this describes the use, result or the impact of the field content or button action, e.g. The help text for the input_location field defined in the stock location model is:

help="Where incoming stock is received."

Help Text Guidelines

  • Help text is written in the English language.
  • In general when writing and reviewing help text, follow the material style guide
    Material Design
  • Help text is a complete sentence. Start with a capital letter and end with a full stop.
  • Try to find some text that provides short additional information.
  • If the use of a field or button is obvious by its name, then it may be better to not provide any help text, instead of a negligible one.
  • Use \n to represent a new line in the client tooltip.
  • On selection fields don’t refer to options. Option names should be self descriptive, and should be reworked, if not.
  • Avoid using this or that when referring to values, e.g.: for a field called end_date:
    Don’t: “Prevent usage after this date.”
    Do: “The last date when the MODEL-NAME can be used.”
  • Avoid using verbs when describing the contents of relational fields, e.g.
    Don’t: “Edit where to store the goods.”
    Do: “The moves that put the stock away into the storage area.”
  • Relational fields can explain the use or impact of the targeted models, e.g.
    For the shipment field defined in the stock move model:
    help="Used to group several stock moves together."
    And the incoming_moves field defined in the stock shipment in model:
    help="The moves that bring the stock into the warehouse."
  • There are fields which implement general functionality and are used in many places in the same way. Try to avoid custom help text for these fields and instead use one of the convenient templates:
    • Name (name): Not normally required.
    • Name (rec_name): The main identifier of the MODEL-NAME.
    • Active: Uncheck to exclude the MODEL-NAME from future use.
    • Sequence: The position of the MODEL-NAME in the list.
    • 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. or
      The PARTY-TYPE’s identifier for the MODEL-NAME.
      where PARTY-TYPE is something like supplier or customer.
    • 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.

Quoting

  • Always use double quotes for help text, as we use double quotes for human readable text, and tooltips are designed to be read by humans.
    Do:
    help="Uncheck to exclude party from future use."
    Don’t:
    help='Uncheck to exclude party from future use.'

Long Strings in Source Code Refresher

  • Multi-line strings are concatenated without needing a +, e.g.:

    help="For explaining concatenation "
    "no explicit plus is needed."

    This is rendered like this when the tooltip is displayed:

        For explaining concatenation no explicit plus is needed.

  • When indenting multi line help text all lines should have the same level of indentation, e.g.:

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

    Don’t:
    help="Multi line help text should "
    _____"not be indented like this."

  • Break long strings after a whitespace, e.g.

    Do:
    help="When explaining using long strings, "
    "you should break after a whitespace"
    help="When explaining using long strings,\n"
    "you should break after a whitespace"

    Don’t:
    help="When explaining using long strings,"
    " don't break before a whitespace"
    help="When explaining using long strings, "
    "\n don't break before a whitespace"

  • Break the line if a sentence ends:

    Do:
    help="When using multiple sentences. "
    "Future code reviews will be easier like this."
    help="When using multiple sentences.\n"
    "Future code reviews will be easier like this."

    Don’t:
    help="When using multiple sentences. Future code "
    "reviews will be harder like this."

Task Overview

  1. Put your name against the module you are starting to add help text to.
  2. Create an issue with title:
    Add help text for MODULE
  3. Write the help texts.
  4. Contribute


List of Tryton Modules

account
account_asset
account_be
account_credit_limit: @pokoli
account_de_skr03
account_deposit
account_dunning
account_dunning_fee
account_dunning_letter
account_fr
account_invoice
account_invoice_correction
account_invoice_history
account_invoice_line_standalone
account_invoice_stock
account_payment
account_payment_clearing
account_payment_sepa
account_payment_sepa_cfonb
account_payment_stripe
account_product: @pokoli
account_statement
account_stock_anglo_saxon
account_stock_continental
account_stock_landed_cost
account_stock_landed_cost_weight
account_tax_rule_country
analytic_account
analytic_invoice
analytic_purchase
analytic_sale
authentication_sms @pokoli - Nothing to do
bank: @pokoli
carrier @xcodinas
carrier_percentage @xcodinas
carrier_weight @xcodinas
commission @pokoli
commission_waiting @pokoli
company @pokoli
company_work_time
country @pokoli
currency @pokoli
customs
dashboard @dave
google_maps
ir @udono
ldap_authentication @pokoli - Nothing to do
party @ced
party_relationship @ced
party_siret
party_vcarddav
product @nicoe
product_attribute @pokoli
product_classification
product_classification_taxonomic
product_cost_fifo @pokoli - Nothing to do
product_cost_history
product_measurements
product_price_list @pokoli
product_price_list_dates
production
production_routing
production_split
production_work
production_work_timesheet
project
project_invoice
project_plan
project_revenue
purchase
purchase_invoice_line_standalone
purchase_request
purchase_requisition
purchase_shipment_cost
res @udono
sale
sale_advance_payment
sale_complaint
sale_credit_limit
sale_extra
sale_invoice_grouping
sale_opportunity
sale_price_list @pokoli
sale_promotion
sale_shipment_cost
sale_shipment_grouping
sale_stock_quantity
sale_supply
sale_supply_drop_shipment
stock @pokoli
stock_forecast
stock_inventory_location
stock_location_sequence
stock_lot
stock_lot_sled
stock_package
stock_package_shipping
stock_package_shipping_dpd
stock_package_shipping_ups
stock_product_location
stock_split
stock_supply
stock_supply_day
stock_supply_forecast
stock_supply_production
timesheet @pokoli
timesheet_cost @pokoli - Nothing to do
tryton
sao
web_user

1 Like
2

There are two kind of tooltips:

  • on fields: I think they should not describe what is going to happen with the value but indeed more why and with which value the field must be filled. Example: “If you have this need, then you should fill with this value”.

  • on buttons: I think they should also not describe what is going to happen because modularity makes it impossible to correctly describe. But instead it should explain why the user should click on it. Example the post button on invoice: “To post into the accounting”.
    Also it should take care that the button can be executed on many records.

3

Usually tooltips should be as concise as possible. I agree that they can be very helpful, but they are basically different from documentation and thus won’t be able to replace it.

I found
[0] Tooltips - Windows apps | Microsoft Learn
[1] Material Design
containing some information how to write application messages.

I think they contain valuable information and perhaps it would be good to extract some agreed guidelines in a document.

While I generally agree with most guidelines in [1] I still would stick to an impersonal style of messages. While [1] recommends to avoid gender ambiguity, it misses the very same problem for personal pronouns. The english ‘you’ can translate to 3 different meanings in German[2] (e.g. 2 in French). For a german translation it is always better to have impersonal source strings.

[2] Personalpronomen – Wikipedia

4

I agree that tooltips can not replace documentation, but they can be reused on the documentation. This is currently available on trytdoc for example to explain the usage of the field/button

5

Guys, there is no need to talk about documentation. We all know there will never be a good documentation. Let’s focus simply on improving the discoverability of Tryton .

6

So my two examples will be better like:

  • “Fill with values if needs”
  • “Post into accounting”
7

Thanks for the references. The information in [1] is high quality and
quite complete about the topic writing style.
IMHO we should directly refer to this document and only name our exceptions.

What you write about the issues in the German language using a personal style of messages are true. But I would prefer another solution. Instead of adding exceptions from French, German or any other language to a common application English language style, we should try to follow one good style for the english language. This provides the best experience for users speaking English.
I would expect the same for French, German and other languages.

So IMHO we should choose the best style on translation, but not change the information, as we already try in the translation.

9

I edited Cedrics proposal with the ideas from the replies and yesterdays discussion results from TUB2016.
Additionally I added an overview the task.
Please comment and edit the wiki page.

10

New Feature idea

Make tool tips editable in-place by the user.

11

You should create a new topic for this feature.

12

I do not find it correct because it implies a system of classification which does not exist most of the time.
Also I do not think the average user will understand this wording.

13
  • There are fields which implements a general functionality and used in many places in the same way. Try to avoid custom help texts for these fields and use instead our convenient templates:
  • Name: The main identifier of the MODEL-NAME.
  • Active: Uncheck to exclude the MODEL-NAME from future use.
  • Sequence: The position of the MODEL-NAME in a list.
  • Parent: The superordinate MODEL-NAME.
  • Childs, Children: The subordinate MODEL-NAMES.
  • Number: The main identification of the MODEL-NAME.
  • Code: The internal identification of the MODEL-NAME.
  • Reference: The identification of an external origin.
  • Origin: The relation to other records.

Shouldn’t the digits field be added too? As is used in the same way in many places.

14

No digits should not have a help because it should never be displayed.

15

As udono proposed on coderview, I think we can use:

Link the MODEL-NAME to a company.

For all the company fields define on the models.
Thoughs?

16

I find it is missing the notion of belonging.

17

To express the notion of belonging I propse to replace Link with add:

Add the MODEL-NAME to a company.

18

Why not: “Make the MODEL-NAME belongs to the company.”

19

Great, I include it on the term list but using “belong” instead of belongs.

1 Like
20

I like it. But is it correct english? E.g.
“Make the Party belongs to the company.” sounds not correct, IMHO.

21

Maybe @jonl could confirm?