Guía de estilo de documentos de Bazel

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

Definición de principios

La documentación de Bazel debe cumplir con los siguientes principios:

• Conciso. Usa la menor cantidad de palabras posible.
• Entendido. 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 toda la documentación.
• Correcto. Escribe de manera que el contenido se mantenga correcto el mayor tiempo posible. Para ello, evita la información basada en el tiempo y las promesas para el futuro.

Escritura

En esta sección, se incluyen sugerencias básicas para escribir.

Encabezados

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

• Haz que los encabezados sean lo más cortos posible. De esta manera, caben en la tabla de contenido sin ajustarse.

  • Sí: Permisos
  • No: Una breve nota sobre los permisos

• Usa mayúscula inicial para los encabezados

  • Sí: Configura tu espacio de trabajo
  • No: Configura tu espacio de trabajo

• Intenta que los encabezados se basen en tareas o acciones. Si los encabezados son conceptuales, pueden basarse en la comprensión, pero escribe sobre lo que hace el usuario.

  • Sí: Conservar el orden del gráfico
  • No: Sobre la conservación del orden del gráfico

Nombres

• Escribe con mayúscula 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 introduzcas nombres nuevos para 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 los términos terminal y línea de comandos en la misma página.

Alcance de la página

• Cada página debe tener un propósito, y este debe definirse 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, indícale al lector qué debe hacer a continuación. En las páginas en las que no hay una acción clara, puedes incluir vínculos a conceptos similares, ejemplos o cualquier otra vía de exploración.

Asunto

En la documentación de Bazel, el público principal deben ser los usuarios, es decir, las personas que usan Bazel para compilar su software.

• Dirígete al lector como "tú". (Si por algún motivo no puedes usar "tú", usa un lenguaje neutral en cuanto al género, como "ellos").

  • Sí: Para compilar código Java con Bazel, debes instalar un JDK.
  • TAL VEZ: 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 principio de la página o en la sección. Otros públicos pueden incluir mantenedores, colaboradores, migradores o cualquier otro rol.

• Evita usar "nosotros". En la documentación para el usuario, no hay autor; solo se les indica 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 está en constante evolución, y realizaremos cambios que, en ocasiones, serán incompatibles y requerirán que los usuarios de Bazel realicen algunos cambios.

Temporal

Cuando sea posible, evita los términos que orientan las cosas en el tiempo, como hacer referencia a fechas específicas (2º trimestre de 2022) o decir "ahora", "actualmente" o "pronto". Estos datos se desactualizan 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 <función>" o un vínculo a un problema de GitHub.

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

Tenso

• Usa el tiempo presente. Evita usar tiempos verbales pasados o futuros, a menos que sea absolutamente necesario para mayor 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, emitirá un error.

• Cuando sea posible, usa la voz activa (en la que un sujeto actúa sobre un objeto) y no la voz pasiva (en la que un objeto recibe la acción de un sujeto). 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 compilará con el resultado.

Tono

Escribe en un tono adecuado 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: Entonces, ¿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 facilitar la lectura, ajusta las líneas a 80 caracteres. Los vínculos largos o los fragmentos de código pueden ser más largos, pero deben comenzar en una línea nueva. Por ejemplo:

Vínculos

• Usa texto de vínculo descriptivo en lugar de "aquí" o "a continuación". Esta práctica facilita el escaneo de un documento y es mejor para los lectores de pantalla.

  • Sí: Para obtener más detalles, consulta [Instalación de Bazel].
  • No: Para obtener más detalles, consulta [aquí].

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

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

Listas

• Usa una lista ordenada para describir cómo completar una tarea con pasos.
• Usa una lista desordenada para enumerar elementos que no se basen en tareas. (Debe haber algún tipo de orden, como alfabético, por importancia, etcétera).
• Escribe con una estructura paralela. Por ejemplo:
  1. Convierte todos los elementos de la lista en oraciones.
  2. Comienza con verbos que estén en 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 inversa: \<example\>.

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

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

Índice

Usa el CDE generado automáticamente que admite el sitio. No agregues un índice manual.

Código

Los ejemplos de código son los mejores amigos de los desarrolladores. Es probable que ya sepas cómo escribir estos mensajes, pero aquí tienes algunas sugerencias.

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

Bloques de código

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

```shell
...

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

Formato de código intercalado

• Usa el estilo de código para los nombres de archivos, directorios, rutas y pequeños fragmentos de código.
• Usa el estilo de código intercalado 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".