Gracias por contribuir a la documentación de Bazel. Esto sirve como una guía rápida de estilo de documentación 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.
Principios de definición
Los documentos de Bazel deben respetar los siguientes principios:
- Concisa. Usa la menor cantidad de palabras posible.
- Claro. Usa un lenguaje simple. Escribe sin lenguaje inapropiado para un nivel de lectura de quinto grado.
- Coherente. Usa las mismas palabras o frases para conceptos repetidos en todos los documentos.
- Correcto. Escribe de manera tal que el contenido sea 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 para la escritura.
Encabezados
- Los encabezados a nivel de la página comienzan en H2. (Los encabezados de H1 se usan como títulos de las páginas).
Los encabezados deben ser lo más cortos posible. De esta manera, caben en el TOC sin envolver.
- Sí: Permisos
- No: Una nota breve sobre los permisos
Usa mayúscula inicial para los encabezados
- Sí: Configure su lugar de trabajo
- No: Configure su lugar de trabajo
Trata de que los encabezados se basen en tareas o sean prácticos. Si los encabezados son conceptuales, es posible que se basen en la comprensión, pero deben escribir en lo que hace el usuario.
- Sí: Preservar el orden de los gráficos
- No: Conserva el orden de los gráficos.
Nombres
Usar mayúsculas para 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.
Asegúrate de que sea coherente. No ingrese 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 oraciones de introducción).
Al final de la página, indícale al lector qué hacer a continuación. En las páginas en las que no hay una acción clara, puedes incluir vínculos a conceptos, ejemplos y otras vías similares para explorar.
Subject
En la documentación de Bazel, el público debería ser principalmente usuarios, es decir, las personas que utilizan Bazel para compilar su software.
Dirígete a tu lector como "tú". (Si, por algún motivo, no puedes usar "tú", usa un lenguaje neutro, como ellos).
- Sí: para compilar código Java con Bazel, debes instalar un JDK.
- MAYBE: Para que los usuarios puedan compilar 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 consta de usuarios generales de Bazel, define el público al comienzo de la página o en la sección. Otros públicos pueden incluir colaboradores, colaboradores, migradores, o bien otras funciones.
Evita "nosotros". En los documentos de usuario, no hay un autor. Solo diles 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 se orientan en el tiempo, como referencias a fechas específicas (2o trimestre de 2022) o "ahora", "ahora" o "pronto". Estas quedan inactivas con rapidez y podrían ser incorrectas si es 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 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é remota, probablemente en octubre de 2017.
Tenso
Usa el tiempo presente. Evita el tiempo pasado o futuro, a menos que sea absolutamente necesario para brindar una claridad.
- Sí: Bazel emite un error cuando encuentra dependencias que no cumplen con esta regla.
- No: Si Bazel encuentra una dependencia que no cumpla con esta regla, Bazel emitirá un error.
Cuando sea posible, usa una voz activa (cuando un sujeto actúa sobre un objeto) y no una voz pasiva (cuando un sujeto actúa sobre un objeto). En general, la voz activa hace que las oraciones sean más claras, ya que muestra quién es el responsable. Si la voz activa resta valor a la claridad, usa la voz pasiva.
- Sí: Bazel inicia X y usa el resultado para compilar Y.
- No: Bazel inicia X. Luego, se compilará Y con el resultado.
Tono
Escribe con un tono comercial.
Evita el lenguaje coloquial. Es más difícil traducir frases específicas al inglés.
- Sí: buen conjunto de reglas
- No. ¿Qué es un buen conjunto de reglas?
Evita el uso de lenguaje demasiado formal. Escribe como si le estuvieras explicando el concepto a alguien que tenga curiosidad por la tecnología, pero que no conozca los detalles.
Formato
Tipo de archivo
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
Utiliza un texto descriptivo para el vínculo en lugar de "aquí" o "debajo". Esta práctica facilita el análisis de documentos y es mejor para los lectores de pantalla.
- Sí: Para obtener más información, consulta [Instala Bazel].
- No: Para obtener más información, consulte [aquí].
Si es posible, termine la oración con el vínculo.
- Sí: Para obtener más información, consulte [link].
- 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 sin ordenar para enumerar elementos que no estén basados en tareas. (También debe haber un orden de clasificación, como en orden alfabético, importancia, etc.).
- Escribe con una estructura paralela. Por ejemplo:
- Escribe todas las oraciones en elementos de lista.
- Comienza con los verbos que están en el mismo tiempo.
- Utiliza una lista ordenada si debes seguir algunos pasos.
Marcadores de posición
Usa corchetes angulares para indicar una variable que los usuarios deben cambiar. En Markdown, escapa las comillas angulares con una barra inversa:
\<example\>.- Sí:
bazel help <command>: imprime ayuda y opciones de<command> - No: comando help de bazel: Imprime la ayuda y las opciones para “comando”
- Sí:
Especialmente en el caso de muestras de código complicadas, usa marcadores de posición que tengan sentido en contexto.
Índice
Usa el TOC generado automáticamente que admite el sitio. No agregues un TOC manual.
Programa
Las muestras de código son las mejores amigas de los desarrolladores. Probablemente ya sepas cómo escribirlos, pero aquí tienes algunas sugerencias.
Si haces referencia a un pequeño fragmento de código, puedes incorporarlo en una oración. Si deseas 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, agrega el lenguaje de la muestra para especificar el tipo de bloque de código.
```shell
...
- Separa los comandos y el resultado 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.
- Utilice un estilo de código intercalado en lugar de cursiva, "comillas" o negrita.
- Sí:
bazel help <command>: imprime ayuda y opciones de<command> - No: comando help de bazel: Imprime la ayuda y las opciones para “comando”
- Sí: