Guía de estilo de documentos de Bazel

Informar un problema Ver fuente

Gracias por contribuir a la documentación de Bazel. Esto sirve como una guía de estilo de documentación rápida para comenzar. Si tienes preguntas de 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

Los documentos de Bazel deben cumplir con estos principios:

  • Brevedad. Usa la menor cantidad de palabras posible.
  • Despejado. Usa lenguaje claro. 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 una manera en la que el contenido se mantenga correcto durante el mayor tiempo posible, evitando información y promesas basadas en el tiempo para el futuro.

Escritura

En esta sección, se incluyen sugerencias de escritura básicas.

Encabezados

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

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

    • 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 estén basados en tareas o sean prácticos. Si los encabezados son conceptuales, se pueden basar en la comprensión, pero escriben en lo que hace el usuario.

    • Sí: Preserva el orden del gráfico
    • No: Sobre la preservación del orden del gráfico

Nombres

  • Usa 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 ingreses nombres nuevos para los conceptos existentes. Cuando corresponda, usa el término definido en el Glosario.

    • Por ejemplo, si escribes sobre la emisión de 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 y ejemplos similares, o bien otros medios de exploración.

Asunto

En la documentación de Bazel, el público debe 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 utilizar "tú", utiliza un lenguaje neutro, como el que se menciona a continuación).

    • 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, defínelo al comienzo de la página o en la sección. Otros públicos pueden incluir responsables de mantenimiento, colaboradores, migradores y otras funciones.

  • Evita el "nosotros". En los documentos de 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 está evolucionando y realizaremos cambios en Bazel que, a veces, no serán compatibles y requerirán algunos cambios por parte de los usuarios de Bazel.

Temporales

Siempre que sea posible, evita términos que orienten las cosas en el tiempo, como hacer referencia a fechas específicas (segundo trimestre de 2022) o decir "ahora", "actualmente" o "pronto". Estos se vuelven obsoletos rápidamente y podrían ser incorrectos si se trata de una proyección a futuro. En su lugar, especifica un nivel de versión, por ejemplo, “Bazel X.x y las versiones posteriores son compatibles con <feature>” o un vínculo de problemas de GitHub.

  • Sí: Bazel 0.10.0 o versiones posteriores son compatibles con 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 pasados o futuros, a menos que sea absolutamente necesario para aclararlo.

    • 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, generará 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 perjudica 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 en un tono empresarial.

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

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

  • Evita usar un lenguaje demasiado formal. Escribe como si estuvieras explicándole el concepto a alguien que tenga curiosidad por la tecnología, pero que no conozca los detalles.

Formatos

File type

Para mayor legibilidad, une las líneas a 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:

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

    • Sí: Para obtener más detalles, consulta [cómo instalar Bazel].
    • No: Para obtener más detalles, consulte [aquí].

  • Si es posible, termina 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 enumerar elementos que no se basan en tareas. (igualmente, debería haber un orden de clasificación, por ejemplo, alfabético, importancia, etc.).
  • Escribe con una estructura paralela. Por ejemplo:
    1. Haz que todos los elementos de la lista sean oraciones.
    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 deben cambiar. En Markdown, escapa los corchetes angulares con una barra inversa: \<example\>.

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

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

Índice

Utiliza el Índice generado automáticamente que admite el sitio. No agregues un Índice de contenido manual.

Código

Las muestras de código son las mejores amigas 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 la muestra.
```shell
...
  • Separa los comandos y los resultados en diferentes bloques de código.

Formato de código insertado

  • Usa el estilo de código para nombres de archivo, 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>: Muestra la ayuda y las opciones de <command>.
    • No: bazel help command: Imprime ayuda y opciones para el "comando".