Guía de estilo de documentos de Bazel

Informar un problema . Ver fuente . Por la noche · 7.2 · 7.1 · 7.0 · 6.5 · 6.4

Gracias por contribuir a la documentación de Bazel. Esto sirve como una guía de documentación de Google Cloud para comenzar. Para cualquier pregunta sobre estilo respondida por esta guía, sigue las 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. Para quinto grado, escribe sin jerga de lectura.
  • Coherente. Usar las mismas palabras o frases para conceptos repetidos en todos los documentos.
  • Correcto. Escribir de forma que el contenido sea correcto durante el tiempo que posible si evitas la información basada en el tiempo y las promesas 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, puede basarse en la comprensión, pero escribe en qué 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. Dónde corresponda, usa el término definido en las Glosario.

    • Por ejemplo, si escribes sobre la emisión de comandos en un 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 en la empezando. 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. Para páginas donde no hay una acción clara, puede incluir enlaces a conceptos similares, ejemplos u otras vías de exploración.

Asunto

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

  • Dirígete al lector como "tú". (Si por alguna razón no puedes utilizar "tú", usan un lenguaje neutral, como ellos).

    • Sí: Para compilar código Java con Bazel, haz lo siguiente: 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 Bazel debe instalar un JDK.

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

  • Evita el "nosotros". En los documentos de usuario, no hay autor. para decirles a las personas como sea posible.

    • Sí: A medida que Bazel evoluciona, debes actualizar tu base de código para mantenerlo. compatibilidad.
    • No: Bazel está evolucionando y realizaremos cambios en Bazel que durante la próxima fecha. horarios no serán compatibles y requerirán algunos cambios por parte de los usuarios de Bazel.

Temporales

Cuando sea posible, evita términos que orienten las cosas en el tiempo, como hacer referencia fechas específicas (segundo trimestre de 2022) o “ahora”, “actualmente” o “pronto”. Estos van rápidamente y podría ser incorrecto si se trata de una proyección a futuro. Más bien, especificar un nivel de versión, por ejemplo, “Bazel X.x y versiones posteriores admiten <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 control remoto. el almacenamiento en caché, probablemente en octubre de 2017.

Tenso

  • Usa el tiempo presente. Evita usar tiempos pasados o futuros, a menos que sea absolutamente necesario. para mayor claridad.

    • Sí: Bazel emite un error cuando encuentra dependencias que no se ajusten a esta regla.
    • No, si Bazel encuentra una dependencia que no cumple con esta regla, Bazel emitirá un error.

  • Cuando sea posible, use la voz activa (cuando un sujeto actúe sobre un objeto), no voz pasiva (donde 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 usar la voz activa distrae de la claridad, utiliza la voz pasiva.

    • Sí: Bazel inicia X y usa el salida a la compilación Y.
    • No: Bazel inicia X y, luego, después, Y se compilará con el resultado.

Tono

Escribe en un tono empresarial.

  • Evita el lenguaje coloquial. Es más difícil traducir frases que son 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 explicando para alguien que tiene curiosidad por la tecnología, pero que no conoce los detalles.

Formato

File type

Para mayor legibilidad, une las líneas a 80 caracteres. Vínculos largos o fragmentos de código puede ser más larga, pero debería 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 escanear 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. (No debería haber seguirá siendo un orden de clasificación, como 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>: Copias ayuda y opciones para <command>
    • No: Comando de ayuda de bazel: Ayuda sobre las impresiones y las opciones para "comando"

  • Especialmente para muestras de código complicadas, usa marcadores de posición que tengan sentido en 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 recursos de mejores amigos. Probablemente sepas cómo escribir estos pero estos son 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, utiliza un código. bloque.

Bloques de código

  • Sé breve. Elimina todo el texto redundante o innecesario de un código muestra.
  • 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 estilo de código intercalado en lugar de cursiva, "comillas", o negrita.
    • Sí: bazel help <command>: Copias ayuda y opciones para <command>
    • No: Comando de ayuda de bazel: Ayuda sobre las impresiones y las opciones para "comando"