# How to write tooltips
**URL:** https://discuss.tryton.org/t/how-to-write-tooltips/212
**Category:** Feature
**Tags:** documentation
**Created:** [September 28, 2016, 7:38am UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212 "2016-09-28T07:38:50Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@ced](https://discuss.tryton.org/u/ced)
#### Post date: [September 28, 2016, 7:38am UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/1 "2016-09-28T07:38:50Z")
## 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](https://material.io/design/communication/writing.html)
- 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.:
- When indenting multi line help text all lines should have the same level of indentation, e.g.:
- Break long strings after a whitespace, e.g.
- Break the line if a sentence ends:
## 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](http://www.tryton.org/how-to-contribute.html)…
### 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
---
### Author:  [@ced](https://discuss.tryton.org/u/ced)
#### Post date: [September 28, 2016, 8:27am UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/2 "2016-09-28T08:27:17Z")
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.
---
### Author:  [@yangoon](https://discuss.tryton.org/u/yangoon)
#### Post date: [September 28, 2016, 10:23am UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/3 "2016-09-28T10:23:09Z")
> [@ced](#):
>
> The tooltips/help 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 behaviour.
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.
> [@ced](#):
>
> 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.
I found
[0] [Tooltips - Windows apps | Microsoft Learn](https://msdn.microsoft.com/en-us/windows/uwp/controls-and-patterns/tooltips)
[1] [Material Design](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] [Personalpronomen – Wikipedia](https://de.wikipedia.org/wiki/Personalpronomen)
---
### Author:  [@pokoli](https://discuss.tryton.org/u/pokoli)
#### Post date: [September 28, 2016, 10:38am UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/4 "2016-09-28T10:38:54Z")
> [@yangoon](#):
>
> 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 agree that tooltips can not replace documentation, but they can be reused on the documentation. This is currently available on [trytdoc](http://pythonhosted.org/trydoc/#field) for example to explain the usage of the field/button
---
### Author:  [@ced](https://discuss.tryton.org/u/ced)
#### Post date: [September 28, 2016, 10:41am UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/5 "2016-09-28T10:41:43Z")
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 .
---
### Author:  [@ced](https://discuss.tryton.org/u/ced)
#### Post date: [September 28, 2016, 10:57am UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/6 "2016-09-28T10:57:05Z")
So my two examples will be better like:
- “Fill with _values_ if _needs_”
- “Post into accounting”
---
### Author:  [@udono](https://discuss.tryton.org/u/udono)
#### Post date: [October 20, 2016, 3:02pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/7 "2016-10-20T15:02:29Z")
> [@yangoon](#):
>
> I found
> [0] [Tooltips - Windows apps | Microsoft Learn](https://msdn.microsoft.com/en-us/windows/uwp/controls-and-patterns/tooltips)
> [1] [Material Design](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.
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.
> [@yangoon](#):
>
> 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](https://de.wikipedia.org/wiki/Personalpronomen)
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.
---
### Author:  [@udono](https://discuss.tryton.org/u/udono)
#### Post date: [October 20, 2016, 4:41pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/9 "2016-10-20T16:41:43Z")
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.
---
### Author:  [@udono](https://discuss.tryton.org/u/udono)
#### Post date: [October 20, 2016, 4:44pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/10 "2016-10-20T16:44:35Z")
### New Feature idea
Make tool tips editable in-place by the user.
---
### Author:  [@ced](https://discuss.tryton.org/u/ced)
#### Post date: [October 23, 2016, 9:01pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/11 "2016-10-23T21:01:47Z")
You should create a new topic for this feature.
---
### Author:  [@ced](https://discuss.tryton.org/u/ced)
#### Post date: [March 1, 2017, 11:22pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/12 "2017-03-01T23:22:05Z")
> [@ced](#):
>
> Parent: The superordinate MODEL-NAME.
>
> Childs, Children: The subordinate MODEL-NAMES.
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.
---
### Author:  [@xcodinas](https://discuss.tryton.org/u/xcodinas)
#### Post date: [March 6, 2017, 12:14pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/13 "2017-03-06T12:14:14Z")
> - 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.
---
### Author:  [@ced](https://discuss.tryton.org/u/ced)
#### Post date: [March 6, 2017, 12:37pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/14 "2017-03-06T12:37:26Z")
> [@xcodinas](#):
>
> Shouldn’t the digits field be added too? As is used in the same way in many places.
No digits should not have a help because it should never be displayed.
---
### Author:  [@pokoli](https://discuss.tryton.org/u/pokoli)
#### Post date: [March 7, 2017, 12:01pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/15 "2017-03-07T12:01:35Z")
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?
---
### Author:  [@ced](https://discuss.tryton.org/u/ced)
#### Post date: [March 7, 2017, 12:35pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/16 "2017-03-07T12:35:00Z")
I find it is missing the notion of belonging.
---
### Author:  [@pokoli](https://discuss.tryton.org/u/pokoli)
#### Post date: [March 7, 2017, 2:29pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/17 "2017-03-07T14:29:24Z")
> [@ced](#):
>
> I find it is missing the notion of belonging.
To express the notion of belonging I propse to replace Link with add:
> Add the MODEL-NAME to a company.
---
### Author:  [@ced](https://discuss.tryton.org/u/ced)
#### Post date: [March 7, 2017, 2:50pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/18 "2017-03-07T14:50:17Z")
Why not: “Make the MODEL-NAME belongs to the company.”
---
### Author:  [@pokoli](https://discuss.tryton.org/u/pokoli)
#### Post date: [March 7, 2017, 3:26pm UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/19 "2017-03-07T15:26:59Z")
> [@ced](#):
>
> Why not: “Make the MODEL-NAME belongs to the company.”
Great, I include it on the term list but using “belong” instead of belongs.
---
### Author:  [@udono](https://discuss.tryton.org/u/udono)
#### Post date: [March 16, 2017, 10:05am UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/20 "2017-03-16T10:05:00Z")
> [@ced](#):
>
> Why not: “Make the MODEL-NAME belongs to the company.”
I like it. But is it correct english? E.g.
“Make the Party belongs to the company.” sounds not correct, IMHO.
---
### Author:  [@ced](https://discuss.tryton.org/u/ced)
#### Post date: [March 16, 2017, 10:19am UTC](https://discuss.tryton.org/t/how-to-write-tooltips/212/21 "2017-03-16T10:19:31Z")
Maybe @jonl could confirm?
[Next page](https://discuss.tryton.org/t/how-to-write-tooltips/212.md?page=2)