How to write tooltips

(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?

(Sergi Almacellas Abellana) #22

Yes, it does not sound correct, so that’s why I added:

“Make the party belong to the company”

Which sounds correct to me.

(Jonathan Levy) #23

I agree with @pokoli, “Make the MODEL-NAME belong to the company.”

(Sergi Almacellas Abellana) #24

I’m currently documenting the stock module and I found that there is a State field for each Workflow model. I’m wondering how we should manage this fields. As they are normally readonly my first though is to do not add any help string (but add them to the buttons instead).

Thoughs?

(Cédric Krier) #25

I think we already said that options of selection should not be described in the help text until there is a correct way to extend it.
So I do not see anything to say on the state field except that it is the “The current state of the document”.

(Sergi Almacellas Abellana) #26

Ok, so I’m adding “The current state of the MODEL-NAME” to the convention to be used for all state fields.

(Cédric Krier) #27

But does it add any value? I see no new information in such help.

(Sergi Almacellas Abellana) #28

Yes, it says that’s the current one and it may change in the future.

(Cédric Krier) #29

I would like to get an agreement on the usage of “this”, “that” etc. in the tooltips.
I think we should not use it because it is not really clear what is pointed for some reasons:

  • the thing pointed is not visible on the screen.
  • it could be a shortcut to not precisely name what is pointed.
(Sergi Almacellas Abellana) #30

I agree that we should avoid using “this” and “that” and we should use a direct reference to the object. For example:

BAD: end_date: "Prevent the usage after this date."
GOOD: end_date: “The last date when the MODEL-NAME will be usable.”

(udono) #31

In review58351002 Pokoli raised questions about the using of different terms in X2Many fields.

For the general use of “Add…” for the description of relational list fields Many2Many and One2Many I need some help:

  1. Initially in an empty list field the usage is adding lines from already existing records.
    So the “Add…” seems an adequate term for the list tool tip.

  2. In an already filled list field (filled already by a user or internal by XML), “Add or remove…” (or “Add or delete” in a One2Many) seems a better term for the list tool tips.

  3. Open a form view from an entry in the list view and creating or editing its content is a common shortcut for power users.

  4. The specific functionalities in a list can be different (read only, access, …)

I am looking for a general term for adding/removing/deleting
lines to the list and creating/editing a single line, regardless the specific implementation of the field and if it is already filled or not.

For me “Manage…” is a adequate term for the list tool tip.

And as thinking about, I find “Manage” term would fit better for all relational fields, as they all provide adding/creating and removing new entries and changing filled entries.

(Cédric Krier) #32

I think we were wrong to use ‘verb’ in any help text of a field. A ‘verb’ is an action and so it should be reserved for buttons. And the client already use verb for the relation field buttons.
For me, the relation fields should also have a descriptive help like other fields, because as you said the field can be in many different states.

(Cédric Krier) #33

I would like to add also that for One2Many the help text is often not needed because the name is most of the time good enough and the detailed description come from the field of the target. It is just like we do not have a description for the main Model.