Guía de estilo de documentos de Bazel

Gracias por contribuir a la documentación de Bazel. Esta guía sirve como guía de estilo de documentación rápida para comenzar. Si tienes preguntas sobre el estilo que no se responden en esta guía, sigue la guía de estilo de la documentación para desarrolladores de Google.

Principios de definición

La documentación de Bazel debe cumplir con estos principios:

• Concise. Usa la menor cantidad de palabras posible.
• Entiendo. Usa un lenguaje sencillo. Escribe sin jerga para un nivel de lectura de quinto grado.
• Coherente. Usa las mismas palabras o frases para los conceptos repetidos en todos los documentos.
• Correcto. Escribe de manera que el contenido permanezca correcto durante el mayor tiempo posible evitando la información basada en el tiempo y las promesas para el futuro.

Escritura

Esta sección contiene sugerencias básicas de escritura.

Encabezados

• Los encabezados a nivel de la página comienzan en H2. (Los encabezados H1 se usan como títulos de página).

• Crea encabezados que sean tan cortos como sea razonable. De esta manera, encajan en el TOC sin envolver.

  • Sí: Permisos
  • No: Nota breve sobre los permisos

• Usa mayúscula inicial para los encabezados

  • Sí: Configurar tu lugar de trabajo
  • No: Configurar tu Workspace

• Intenta que los encabezados se basen en tareas o sean prácticos. Si los encabezados son conceptuales, puede basarse en la comprensión, pero escribe sobre lo que hace el usuario.

  • Sí: Conserva el orden del gráfico.
  • No: En la preservación del orden del gráfico

Nombres

• Usa mayúsculas en los nombres propios, como Bazel y Starlark.

  • Sí: Al final de la compilación, Bazel imprime los destinos solicitados.
  • No: Al final de la compilación, bazel imprime los destinos solicitados.

• Mantén la coherencia. No ingreses nombres nuevos para los conceptos existentes. Cuando corresponda, usa el término definido en el Glosario.

  • Por ejemplo, si escribes sobre cómo emitir comandos en una terminal, no uses la terminal y la línea de comandos en la página.

Alcance de la página

• Cada página debe tener un propósito, que se debe definir al principio. Esto ayuda a los lectores a encontrar lo que necesitan más rápido.

  • Sí: En esta página, se explica cómo instalar Bazel en Windows.
  • No (sin oración introductoria).

• Al final de la página, dile al lector qué debe hacer a continuación. En el caso de las páginas en las que no hay una acción clara, puedes incluir vínculos a conceptos, ejemplos o otras vías de exploración similares.

Asunto

En la documentación de Bazel, el público debe ser principalmente de usuarios, las personas que usan Bazel para compilar su software.

• Apódate a tu lector como “tú”. (Si por algún motivo no puedes usar “tú”, usa un lenguaje neutro en cuanto al género, como “ellos”).

  • Sí: Para compilar código Java con Bazel, debes instalar un JDK.
  • MAYBE: Para que los usuarios compilen código Java con Bazel, deben instalar un JDK.
  • No: Para que un usuario compile código Java con Bazel, debe instalar un JDK.

• Si tu público NO son usuarios generales de Bazel, define el público al comienzo de la página o en la sección. Otros públicos pueden incluir a los encargados del mantenimiento, a los colaboradores, a los migradores y a otros roles.

• Evita el uso de "nosotros". En los documentos para el usuario, no hay autor. Solo diles a las personas lo que es posible.

  • Sí: A medida que Bazel evoluciona, debes actualizar tu base de código para mantener la compatibilidad.
  • No: Bazel evoluciona, y realizaremos cambios en Bazel que, a veces, serán incompatibles y requerirán algunos cambios de los usuarios de Bazel.

Temporales

Siempre que sea posible, evita los términos que orienten los elementos en el tiempo, como hacer referencia a fechas específicas (2º trimestre de 2022) o decir "ahora", "actualmente" o "pronto". Se vuelven obsoletos rápidamente y podrían ser incorrectos si se trata de una proyección futura. En su lugar, especifica un nivel de versión, como “Bazel X.x y versiones posteriores admiten <feature>” o un vínculo a un problema de GitHub.

• Sí: Bazel 0.10.0 o versiones posteriores admiten la almacenamiento en caché remoto.
• No: Bazel pronto admitirá la caché remota, probablemente en octubre de 2017.

Tenso

• Usa el presente. Evita el tiempo pasado o futuro, a menos que sea absolutamente necesario para la claridad.

  • Sí: Bazel emite un error cuando encuentra dependencias que no cumplen con esta regla.
  • No: Si Bazel encuentra una dependencia que no cumple con esta regla, Bazel mostrará un error.

• Cuando sea posible, usa la voz activa (cuando un sujeto actúa sobre un objeto), no la voz pasiva (cuando un sujeto actúa sobre un objeto). En general, la voz activa hace que las oraciones sean más claras porque muestra quién es responsable. Si el uso de la voz activa resta claridad, usa la voz pasiva.

  • Sí: Bazel inicia X y usa el resultado para compilar Y.
  • No: Bazel inicia X y, luego, Y se compila con el resultado.

Tono

Escribe en un tono amigable para las empresas.

• Evita el lenguaje coloquial. Es más difícil traducir frases específicas del inglés.

  • Sí: Conjuntos de reglas buenos
  • No: ¿Qué es un buen conjunto de reglas?

• Evita el lenguaje demasiado formal. Escribe como si le explicaras el concepto a alguien que siente curiosidad por la tecnología, pero no conoce los detalles.

Formato

File type

Para mejorar la legibilidad, une las líneas en 80 caracteres. Los vínculos o fragmentos de código largos pueden ser más largos, pero deben comenzar en una línea nueva. Por ejemplo:

Vínculos

• Usa texto descriptivo en los vínculos en lugar de "aquí" o "más abajo". Esta práctica facilita el escaneo de un documento y es mejor para los lectores de pantalla.

  • Sí: Para obtener más información, consulta [Cómo instalar Bazel].
  • No: Para obtener más información, consulta [aquí].

• Si es posible, termina la oración con el vínculo.

  • Sí: Para obtener más información, consulta [vínculo].
  • No: Consulta [link] para obtener más información.

Listas

• Usa una lista ordenada para describir cómo realizar una tarea con pasos
• Usa una lista desordenada para enumerar elementos que no se basan en tareas. (Debe haber un orden de clasificación, como alfabético, importancia, etcétera).
• Escribe con una estructura paralela. Por ejemplo:
  1. Haz que todos los elementos de la lista sean oraciones.
  2. Comienza con verbos que tengan el mismo tiempo.
  3. Usa una lista ordenada si hay pasos que seguir.

Marcadores de posición

• Usa corchetes angulares para denotar una variable que los usuarios deben cambiar. En Markdown, escapa los corchetes angulares con una barra invertida: \<example\>.

  • Sí: bazel help <command>: Imprime ayuda y opciones para <command>.
  • No: bazel help command: Imprime ayuda y opciones para “command”.

• En especial, para muestras de código complicadas, usa marcadores de posición que tengan sentido en el contexto.

Índice

Usa el glosario generado automáticamente que admite el sitio. No agregues un glosario manual.

Código

Los ejemplos de código son los mejores amigos de los desarrolladores. Probablemente ya sepas cómo escribirlos, pero aquí tienes algunos consejos.

Si haces referencia a un pequeño fragmento de código, puedes incorporarlo en una oración. Si quieres que el lector use el código, como copiar un comando, usa un bloque de código.

Bloques de código

• Sé breve. Elimina todo el texto redundante o innecesario de un ejemplo de código.
• En Markdown, especifica el tipo de bloque de código agregando el lenguaje del ejemplo.

```shell
...

• Separa los comandos y los resultados en diferentes bloques de código.

Formato de código intercalado

• Usa el estilo de código para los nombres de archivos, directorios, rutas de acceso y pequeños fragmentos de código.
• Usa estilos de código intercalados en lugar de cursiva, "comillas" o negrita.
  • Sí: bazel help <command>: Imprime ayuda y opciones para <command>.
  • No: bazel help command: Imprime ayuda y opciones para “command”.