Gracias por contribuir a la documentación de Bazel. Esta guía de estilo de documentación rápida te ayudará a 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 los siguientes principios:
- Conciso. Usa la menor cantidad de palabras posible.
- Claro. 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 los documentos.
- Correcto. Escribe de manera que el contenido siga siendo correcto durante el mayor tiempo posible . Para ello, evita la información basada en el tiempo y las promesas para el futuro.
Escritura
Esta sección contiene sugerencias básicas de escritura.
Encabezados
- Los encabezados a nivel de la página comienzan en H2. (Los encabezados H1 se usan como títulos de página).
Haz que los encabezados sean lo más breves posible. De esta manera, caben en la tabla de contenido sin ajuste de línea.
- 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 sean prácticos. Si los encabezados son conceptuales, pueden basarse en la comprensión, pero escribe sobre lo que hace el usuario.
- Sí: Cómo 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.
Usa un enfoque coherente. No introduzcas nombres nuevos para 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 terminal y 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, dile 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 otras vías de exploración.
Asunto
En la documentación de Bazel, el público debe ser principalmente 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 comienzo de la página o en la sección. Otros públicos pueden incluir administradores, colaboradores, migradores o cualquier otro rol.
Evita usar "nosotros". En los documentos para usuarios, no hay 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 haremos cambios en Bazel que, a veces, serán incompatibles y requerirán algunos cambios por parte de los usuarios de Bazel.
Temporal
Cuando sea posible, evita los términos que orientan 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 futura. En su lugar, especifica un nivel de versión, como "Bazel X.x y versiones posteriores admiten <feature> 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 el tiempo pasado o futuro, a menos que sea absolutamente necesario para la 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, Bazel emitirá un error.
Cuando sea posible, usa la voz activa (en la que un sujeto actúa sobre un objeto) en lugar de la voz pasiva (en la que un objeto es afectado por 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, se compilará Y con el resultado.
Tono
Escribe con un tono empresarial.
Evita el lenguaje coloquial. Es más difícil traducir frases que son específicas del inglés.
- Sí: Buenos conjuntos de reglas
- No: ¿Qué es un buen conjunto de reglas?
Evita el lenguaje demasiado formal. Escribe como si le explicaras el concepto a alguien que tiene curiosidad por la tecnología, pero no conoce los detalles.
Formato
Tipo de archivo
Para mejorar la legibilidad, 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 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í].
Finaliza la oración con el vínculo, si es posible.
- 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 realizar una tarea con pasos.
- Usa una lista desordenada para enumerar elementos que no se basan en tareas. (Debe haber un orden, como alfabético, de importancia, etcétera).
- Escribe con una estructura paralela. Por ejemplo:
- Haz que todos los elementos de la lista sean oraciones.
- Comienza con verbos que tengan el mismo tiempo.
- 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 la ayuda y las opciones de<command>. - No: bazel help command: Imprime la ayuda y las opciones de "command".
- Sí:
En especial para las muestras de código complicadas, usa marcadores de posición que tengan sentido en el contexto.
Índice
Usa la tabla de contenido generada automáticamente que admite el sitio. No agregues una tabla de contenido manual.
Código
Las muestras de código son el mejor amigo de los desarrolladores. Es probable que ya sepas cómo escribirlas ya, 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, 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 el resultado en diferentes bloques de código.
Formato de código intercalado
- Usa el estilo de código para los nombres de archivos, los directorios, las rutas de acceso y los fragmentos de código pequeños.
- Usa el estilo de código intercalado en lugar de cursiva, "comillas" o negrita.
- Sí:
bazel help <command>: Imprime la ayuda y las opciones de<command>. - No: bazel help command: Imprime la ayuda y las opciones de "command".
- Sí: