Guías para textos de ayuda

Propósito

The help messages for fields, buttons and selection values, which are displayed as tooltips in the client, are very useful for new users who are discovering Tryton and existing users who need to refresh their memory.

These help messages are part of Tryton's documentation and are great because they are easily displayed to users, at the time and place where they need to see them. They are also close to the code, as they are defined in the help parameters to fields, which helps developers keep them up to date, and allows them to be shown in the user's language.

These guidelines provide some clear rules on how to write this help text, so it is kept consistent and accurate across the whole application.

El texto de ayuda debe responder la pregunta:

¿Qué es esto o para qué sirve?

If it is obvious what it is for, or what it does, then it is often better not to add any help text.

Estilo general

En general, deberías intentar seguir el material design style guide.

Idioma

  • The help text is always written in English, Tryton will automatically display it in the user's language if a translation for it is available.
  • Write in complete sentences, starting with a capital letter and ending with a full stop.
  • Try and write text that adds useful information in a clear, accurate and concise way. Normally help text will be no more that one or two lines long.

Formato

Guías generales de formato aplicables a todos los tipos de texto de ayuda:

  • Always use double quotes for help text. In Tryton double quotes are normally used for human readable text, and help text is designed to be read by humans.
  • Si necesitas agregar un salto de línea, puedes hacerlo usando \n in the help text.
  • Las cadenas multilínea se concatenan sin necesitar un operador (+).
  • Indenta el texto de ayuda multilínea para que todo tenga el mismo nivel de indentación: 
    help="Multi-line help text should "
"all have the same level of indentation."
  • Divide las cadenas largas después de un espacio en blanco: 
    help="You should break long "
"strings after a whitespace,\n"
"not before."
  • Empieza cada oración en una línea nueva: 
    help="When using multiple sentences. "
"Code reviews will be easier like this."

Botones

  • Help text for buttons should describe the action or impact of pressing the button.

Campos

  • Evita usar this o that when referring to the field's value because the help text may be used when the value is not visible:
    Usa: "La última fecha en la que se puede usar MODEL-NAME."
    Evitar: "Impedir su uso después de esta fecha."
  • On selection fields don't refer to the selection's options, these may change depending on what modules are activated.
  • Help text for fields should describe either what is contained in the field or what it is used for. Avoid using verbs for these:
    Usa: "Usado para agrupar movimientos de stock."
    Usa: "Los movimientos que guardan el stock en el área de almacenamiento."
    Evitar: "Editar dónde almacenar la mercancía."

Texto de ayuda estándar

Campos

Some fields implement general functionality and are used in many different places in the same way. To keep things consistent use one of the standard help text values for these:

Nombre (name):
Esto debería ser bastante obvio, por lo que normalmente no requiere texto de ayuda.
Nombre (rec_name):
El identificador principal para el MODEL-NAME.
Padre:
Used to add structure above the MODEL-NAME.
Hijos:
Used to add structure below the MODEL-NAME.
Número:
El identificador principal para el MODEL-NAME.
Código:
El identificador interno para el MODEL-NAME.
Referencia:
El identificador externo para el MODEL-NAME.
Origin:
La fuente del MODEL-NAME.
Empresa:
La empresa que el MODEL-NAME is associated with.
Estado:
El estado actual de MODEL-NAME.