How to write tooltips

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


(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.”