Yes, it does not sound correct, so that’s why I added:
“Make the party belong to the company”
Which sounds correct to me.
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?
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”.
Ok, so I’m adding “The current state of the MODEL-NAME” to the convention to be used for all state fields.
But does it add any value? I see no new information in such help.
Yes, it says that’s the current one and it may change in the future.
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.
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.”
1 Like
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:
-
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. -
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.
-
Open a form view from an entry in the list view and creating or editing its content is a common shortcut for power users.
-
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.
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.
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.
I know I am quite late to this discussion, but I would like to look at reviewing/adding help text for some modules.
Before I start doing that I would like to make sure I get things right, so I would like to suggest some changes to the convenient templates, and get peoples feedback on them.
I think I agree with Cédric when he says:
So I have tried to take that into account.
Template Suggestions:
I think this one is quite difficult to add help to. To me the word identifier suggests that this is some kind of code, which it may be in some cases, but I don’t think this works for things like party names.
A few alternative suggestions are:
- The main name for the MODEL-NAME.
- The main label for the MODEL-NAME.
- What the MODEL-NAME is called. (I think I like this one best)
The position of the MODEL-NAME in the list.
e.g. The position of the sales line in the list.
Quick side question, how does this help text get applied to classes that inherit the sequence_ordered?
The parent above the MODEL-NAME.
e.g. The parent above the location.
The children below the MODEL-NAME.
e.g. The children below the location.
Small note for future reference, child or children, never childs (except child’s when indicating something that belongs to the child)
The main identifier for the MODEL-NAME.
e.g. The main identifier for the inventory.
The internal identifier used for the MODEL-NAME.
e.g. The internal identifier used for the inventory.
Why “used”? I’ll try and explain, I suggest “used”, because the main reason for this identifier is to make it easier to refer to this item internally, and so it will be mainly/only be “used” internally. For me the other identifiers main purposes are to name the item.
The external identifier for the MODEL-NAME.
e.g. The external identifier for the invoice.
The source of the MODEL-NAME.
e.g. The source of the invoice.
I can see this has already been discussed, and I only suggest this because it seems wrong to say that certain documents that are created by external companies (such as supplier delivery notes or invoices) “belong” to the company.
The reason is that if someone phoned up from the external company they would sometimes refer to them as “our” invoices, e.g. “Have you processed our invoices yet?”.
So I suggest:
The company that the MODEL-NAME is associated with.
e.g. The company that the stock move is associated with.
1 Like
It should apply only on rec_name and this field should be an identifier.
I guess it was lost. We would need of a generic help that apply to any model (indeed I think it should be a general rule to try to avoid to name external things because it makes it less modular).
Indeed, I’m wondering if parent/child should really been explained.
I do not see why it will mean “used internally”. The other identifier are also used externally or both.
It looks OK and replace the verb which is good.
It could be done here: https://codereview.tryton.org/58351003/diff/40001/trytond/model/order.py#new-line-7
I’m not too sure I follow, let me try and clarify.
I know that there is also a rec_name, but I my understanding was that name is what the item is called (e.g. what the tax is called), and rec_name is what the record is called (e.g. what the record that represents the tax is called), and commonly these will be the same name, as the name of the item is generally a good name for the record.
There are name fields where describing them as an identifier would not be right. The best example is the name field on party. Nobody would say “Hi, my identifier is Dave”, but in all the cases that I could see it sounds right to say the name is what the item is called (e.g. that location is called ‘LC123’, or that person is called Dave).
Having said all of this, do you think a tooltip is needed for name?
The only other thing that I thought could be said about theses fields was that they are “Used to add structure to the MODEL-NAMEs.” e.g. Used to add structure to the locations, but I am unsure whether this would be a worthwhile tooltip.
Okay, no problem, then:
The internal identifier for the MODEL-NAME.
e.g. The internal identifier for the inventory.
Not for name field but for rec_name field (which is labelled “Name”) it should be described as the identifier.
I’ve just been looking at the shipments in the stock module, and this help text is not very clear for the shipment references, maybe this would be better as:
The EXTERNAL-PARTY’s identifier for the MODEL-NAME.
e.g. The supplier’s identifier for the shipment.
And for other cases where there may, or may not be, one or more external identifiers:
The external identifiers for the MODEL-NAME.
e.g. The external identifiers for the internal shipment.
This post is just to inform everyone that I’ve updated the help text guidelines to bring them up to date with all the items discussed in this topic, so they correctly describe the current best practices to use when writing help text.
1 Like
This topic was automatically closed after 12 days. New replies are no longer allowed.