Guía de estilo de documentos de Bazel

Gracias por colaborar con la documentación de Bazel. Esto sirve como una 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, consulta la Guía de estilo de la documentación para desarrolladores de Google.

Definición de principios

Los documentos de Bazel deben cumplir con estos principios:

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

Escritura

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

Encabezados

  • Los encabezados de nivel de página comienzan en el segundo semestre. (Los encabezados de H1 se usan como títulos de las páginas).

  • Haz que los encabezados sean tan cortos como sean razonables. De esta forma, encajan en el TOC sin envolver.

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

  • Usa mayúscula inicial para los encabezados

    • Sí: Configurar el lugar de trabajo.
    • No: Configurar tu lugar de trabajo

  • Intenta crear encabezados basados en tareas o prácticos. Si los encabezados son conceptuales, puede basarse en la comprensión, pero escribir en lo que hace el usuario.

    • Sí: Se preserva el orden del gráfico.
    • No: Se usa para preservar el orden del gráfico.

Nombres

  • Usar mayúsculas en los sustantivos 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 los conceptos existentes. Cuando corresponda, usa el término definido en el Glosario.

    • Por ejemplo, si escribes acerca de 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, indícale al lector qué 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 vías de exploración similares.

Asunto

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

  • Dirígete al lector como "tú". (Si, por alguna razón, no puedes usar la frase "tú", usa un lenguaje neutro, como en este caso).

    • 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 incluye usuarios generales de Bazel, defínelo al comienzo de la página o en la sección. Otros públicos pueden incluir a los encargados de mantenimiento, colaboradores, migradores y otros roles.

  • Evita "nosotros". En los documentos de usuario, no hay autor; simplemente cuéntales a las personas lo que es posible.

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

Temporal

Siempre que sea posible, evita los términos que orienten las cosas en el tiempo, como hacer referencia a fechas específicas (2o trim. 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 las versiones posteriores admiten <feature> o un vínculo de problemas 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 el tiempo pasado o futuro, a menos que sea absolutamente necesario para brindar mayor claridad.

    • Sí: Bazel genera 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.

  • Siempre que sea posible, usa la voz activa (cuando un sujeto actúa sobre un objeto) y no la voz pasiva (cuando un sujeto actúa sobre un objeto). En general, la voz activa aclara las oraciones, ya que muestra quién es el responsable. Si el uso de la voz activa le resta claridad a la 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 con un tono amigable para los negocios.

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

    • Sí: Conjuntos de reglas correctos
    • No: ¿Cuál es un buen conjunto de reglas?

  • Evita utilizar un lenguaje demasiado formal. Escribe como si le estuvieras explicando el concepto a alguien que tiene 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:

  • En lugar de "aquí" o "abajo", usa un texto descriptivo para los vínculos. Esta práctica facilita el análisis de un documento y es mejor para los lectores de pantalla.

    • Sí: Para obtener más detalles, consulta [Instala Bazel].
    • No: Para obtener más detalles, consulta [aquí].

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

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

Listas

  • Usar una lista ordenada para describir cómo realizar una tarea con pasos
  • Usa una lista sin ordenar para indicar elementos que no están basados en tareas. (debería haber un orden de clasificación, por ejemplo, alfabético, de importancia, etcétera).
  • Escribe con una estructura paralela. Por ejemplo:
    1. Crea todas las oraciones de los elementos de la lista.
    2. Comienza con verbos que estén en el mismo tiempo.
    3. Usa una lista ordenada si hay pasos a seguir.

Marcadores de posición

  • Usa corchetes angulares para indicar una variable que los usuarios deberían cambiar. En Markdown, usa una barra inversa para escapar los corchetes angulares: \<example\>.

    • Sí: bazel help <command>: Muestra la ayuda y las opciones para <command>.
    • No: Ayuda de bazel comando: Imprime la ayuda y las opciones de “comando”.

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

Índice

Usa el TOC generado automáticamente que admita el sitio. No agregues una TOC manual.

Código

Las muestras 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 una muestra de código.
  • En Markdown, especifica el tipo de bloque de código agregando el lenguaje de muestra.
```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 nombres de archivos, directorios, rutas de acceso y pequeños fragmentos de código.
  • Usa estilo de código intercalado en lugar de cursiva, "comillas" o negrita.
    • Sí: bazel help <command>: Muestra la ayuda y las opciones para <command>.
    • No: Ayuda de bazel comando: Imprime la ayuda y las opciones de “comando”.