How to write tooltips


(Cédric Krier) #1

Rational

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 way, 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 how to write them, to be consistent across the all application and take care of the possible extension changing the behavior.

Proposal

A help text answers the question:

What is this field/button for?

The answering help text describes the use, result or the impact of the field content or button action.
E.g. the help text of the category field defined in the party module is:

`help='Add categories to group sets of related parties.'`

Help Text Guidelines

  • Help text is written in English language.
  • In general at writing and reviewing help texts, take care of the material style guide
    https://material.google.com/style/writing.html#writing-global-writing
  • A help text is a complete sentence. Start with a capitalized first letter and end with a colon.
  • Try to find a text which provides a short additional information.
  • The use of a field or button could be obvious by its name. So it may be better to not provide a 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.
  • Relational fields are explaining the use or impact of the targeting models. E.g. Language field on Party model:
    help="Use to translate automated communication with the party."
    E.g. the help text of the category field defined in the party module is:
    help="Add categories to group sets of related parties."
  • 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: Add the MODEL-NAME below the parent.
  • Childs, Children: Add childs below the MODEL-NAME.
  • 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.
  • Company: Make the MODEL-NAME belong to the company.
  • State: The current state of the MODEL-NAME

Quoting

  • Always use double quotes to quote help texts, as we use double quotes for human readable texts, 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 +. E.g.:
    help="For explaining concatenation "
    "no explicit plus needed."
    Is rendered like this in the tooltip representation:
    For explaining concatenation no explicit plus needed.
  • Break a long string after a whitespace. E.g.
    Do:
    help="For explaining long string, we are "
    "required to break after a whitespace"
    help="For explaining long string, we are\n"
    "required to break after a whitespace"
    Don’t:
    help="For explaining long string, we are"
    ' required to break after a whitespace'
    help="For explaining long string, we are "
    "\n required to break after a whitespace"
  • Break the line if a sentence ends:
    Do:
    help="For explain multiple sentences. "
    "Future code reviews will thank it."
    help="For explain multiple sentences.\n"
    "Future code reviews will thank it."
    Don’t:
    help="For explain multiple sentences. Because future "
    "code reviews will thank it."

Task Overview

  1. Put your name on the module you are starting to add help texts.
  2. Create an issue with title:
    Add help text for MODULE
  3. Write 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
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


(Cédric Krier) #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.


(Mathias Behrle) #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] https://msdn.microsoft.com/en-us/windows/uwp/controls-and-patterns/tooltips
[1] https://material.google.com/style/writing.html
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] https://de.wikipedia.org/wiki/Personalpronomen


(Sergi Almacellas Abellana) #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


(Cédric Krier) #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 .


(Cédric Krier) #6

So my two examples will be better like:

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

(udono) #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.


(udono) #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.


(udono) #10

New Feature idea

Make tool tips editable in-place by the user.


(Cédric Krier) #11

You should create a new topic for this feature.


(Cédric Krier) #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.


(Xavier) #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.


(Cédric Krier) #14

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


(Sergi Almacellas Abellana) #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?


(Cédric Krier) #16

I find it is missing the notion of belonging.


(Sergi Almacellas Abellana) #17

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

Add the MODEL-NAME to a company.


(Cédric Krier) #18

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


(Sergi Almacellas Abellana) #19

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


(udono) #20

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


(Cédric Krier) #21

Maybe @jonl could confirm?