Guías para textos de ayuda

Propósito

Los mensajes de ayuda para campos, botones y valores de selección, que se muestran como información sobre herramientas en el cliente, son muy útiles para nuevos usuarios que están descubriendo Tryton y para usuarios existentes que necesitan refrescar su memoria.

Estos mensajes de ayuda son parte de la documentación de Tryton y son excelentes porque se muestran fácilmente a los usuarios, en el momento y lugar donde necesitan verlos. También están cerca del código, tal como se definen en elhelpparámetros a los campos, lo que ayuda a los desarrolladores a mantenerlos actualizados y permite mostrarlos en el idioma del usuario.

Estas pautas proporcionan algunas reglas claras sobre cómo escribir este texto de ayuda, para que se mantenga coherente y preciso en toda la aplicación.

El texto de ayuda debe responder la pregunta:

¿Qué es esto o para qué sirve?

Si es obvio para qué sirve o para qué sirve, a menudo es mejor no añadir ningún texto de ayuda.

Estilo general

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

Idioma

  • El texto de ayuda siempre está escrito en inglés, Tryton lo mostrará automáticamente en el idioma del usuario si hay una traducción disponible.
  • Escribe oraciones completas, comenzando con mayúscula y terminando con punto.
  • Intente escribir texto que agregue información útil de manera clara, precisa y concisa. Normalmente el texto de ayuda no tendrá más de una o dos líneas.

Formato

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

  • Usa siempre comillas dobles para el texto de ayuda. En Tryton, las comillas dobles normalmente se usan para texto legible por personas, y el texto de ayuda está diseñado para ser leído por personas.
  • Si necesitas agregar un salto de línea, puedes hacerlo usando\nen el texto de ayuda.
  • 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

  • El texto de ayuda para los botones debe describir la acción o el impacto de presionar el botón.

Campos

  • Evita usarthisothatal hacer referencia al valor del campo porque el texto de ayuda puede usarse cuando el valor no es visible:
    Usa: "La última fecha en la que se puede usar MODEL-NAME."
    Evitar: "Impedir su uso después de esta fecha."
  • Los campos de selección no hacen referencia a las opciones de selección, estas pueden cambiar dependiendo de qué módulos estén activados.
  • El texto de ayuda para los campos debe describir lo que contiene el campo o para qué se utiliza. Evite el uso de verbos para estos:
    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

Algunos campos implementan una funcionalidad general y se utilizan en muchos lugares diferentes de la misma manera. Para mantener la coherencia, utilice uno de los valores de texto de ayuda estándar para estos:

Nombre(name):
Esto debería ser bastante obvio, por lo que normalmente no requiere texto de ayuda.
Nombre(rec_name):
El identificador principal para elMODEL-NAME.
Padre:
Se utiliza para agregar estructura sobre elMODEL-NAME.
Hijos:
Se utiliza para agregar estructura debajo delMODEL-NAME.
Número:
El identificador principal para elMODEL-NAME.
Código:
El identificador interno para elMODEL-NAME.
Referencia:
El identificador externo para elMODEL-NAME.
Origin:
La fuente delMODEL-NAME.
Empresa:
La empresa que elMODEL-NAME is associated with.
Estado:
El estado actual deMODEL-NAME.