Escribir páginas breves que muestran los usos más comunes de un comando

## Buscar si ya existe la página y elegir su carpeta según el sistema Busque el comando en todos los árboles de páginas originales y traducidas antes de crear nada. Si ya existe una página, edítela en lugar de crear un duplicado. Si no existe, determine dónde funciona realmente la sintaxis documentada. - Coloque un comando en el directorio común solo cuando la misma sintaxis funcione en al menos dos plataformas. - Coloque un comando que funciona en una sola plataforma en el directorio de esa plataforma. - Mantenga las páginas en inglés en el árbol principal y las traducciones en árboles específicos de cada configuración regional, con la misma ruta de plataforma. - Use nombres de archivo en minúsculas, salvo que una política específica de la plataforma exija respetar las mayúsculas y minúsculas canónicas del comando en el título de la página o en su invocación. No elija un directorio por la reputación o el nombre del comando. Verifique primero las plataformas compatibles y la sintaxis. ## Mantener la página corta, con el título y la descripción antes de los ejemplos Escriba cada página como una pequeña referencia Markdown con esta secuencia fija: 1. Un solo H1 cuyo nombre de comando coincida con el nombre del archivo, sin tener en cuenta las mayúsculas y minúsculas cuando el repositorio lo permita. 2. Una descripción en bloque de cita, preferiblemente de una o dos líneas. 3. Una línea obligatoria de «Más información» que contenga una URL de la fuente original entre paréntesis angulares. 4. Ejemplos prácticos, cada uno con una descripción en viñeta y en modo imperativo, seguida de una línea separada con el comando en código en línea. 5. Un salto de línea al final del archivo. Use cinco ejemplos de forma predeterminada y nunca supere los ocho. Deje una línea en blanco entre la descripción y el comando, y entre los ejemplos. No use negrita, cursiva ni Markdown decorativo en el contenido de la página. ## Elegir ejemplos para las tareas reales más comunes Seleccione ejemplos que resuelvan las tareas reales más habituales. Redacte las descripciones en modo imperativo: «Enumere los archivos», no «Enumera los archivos». Manténgalas breves y orientadas a la acción, y no explique conceptos generales del sistema operativo. Verifique cada ejemplo con el manual del comando, la ayuda integrada o la documentación oficial. Conserve el espacio documentado entre las opciones y los argumentos; use `--option arg` salvo que el comando exija explícitamente otra forma. Coloque «Mostrar la ayuda» y «Mostrar la versión» como los dos últimos ejemplos, en ese orden, cuando existan esas invocaciones. Son ejemplos de menor prioridad, por lo que puede omitir uno si hace falta un ejemplo práctico más útil y se superaría el límite de la página. ## Marcar con llaves dobles las partes que el usuario debe cambiar Encierre los valores reemplazables entre llaves dobles. Use de forma coherente marcadores de posición con estas formas semánticas: - `{{path/to/file}}`, `{{path/to/directory}}` y `{{filename}}` para entradas del sistema de archivos; - `{{file1 file2 ...}}` para varios argumentos; - `{{option1|option2}}` para alternativas; - `{{1..5}}` para intervalos numéricos y `{{*.ext}}` para patrones con comodines; - `{{[-v|--verbose]}}` para opciones cortas y largas equivalentes; - `{{[-it|--interactive --tty]}}` para indicadores agrupados. Cuando existan tanto la forma corta como la larga, muestre ambas. Nunca invente una forma corta: los indicadores de versión y otras opciones comunes varían según el comando. No anide marcadores de posición ni sustituya la sintaxis obligatoria de llaves dobles por llaves simples o corchetes. Use paréntesis angulares para las pulsaciones de teclas: `<a>`, `<Enter>`, `<Space>`, `<Ctrl>`, `<Alt>` y `<Shift>`. Escriba las combinaciones con un espacio, como `<Ctrl c>`, y las secuencias como grupos adyacentes, como `<Esc><u>`. ## Enlazar el manual oficial tras comprobar que el enlace funciona Todas las páginas deben incluir un enlace a más información. Dé prioridad al manual oficial del comando, la documentación del proyecto, un servicio de páginas de manual que se mantenga actualizado o la documentación del proveedor de la plataforma. Antes de aceptar un enlace, siga las redirecciones y confirme que la respuesta final sea correcta. No confíe en una URL solo porque parezca plausible. Mantenga el enlace entre paréntesis angulares en la línea exclusiva de «Más información» y evite las fuentes promocionales o no oficiales cuando exista una fuente primaria. Use las mismas fuentes autorizadas para confirmar los nombres de comandos, las formas de las opciones, el espacio entre argumentos, el comportamiento en cada plataforma, la sintaxis de ayuda y la sintaxis de versión. ## Escribir rutas y variables como lo esperan Windows y otros sistemas En las páginas de comandos de Windows, mantenga los nombres de archivo en minúsculas salvo que la política del repositorio indique lo contrario, pero conserve las mayúsculas y minúsculas canónicas del comando en el H1 y en los ejemplos. Use barras invertidas en los marcadores de posición de rutas. Escriba las variables de entorno con la sintaxis del shell documentado: `%VARIABLE%` para el intérprete de comandos tradicional y `$Env:VARIABLE` para PowerShell. Los ejemplos destinados a PowerShell deben funcionar tanto en la edición compatible más antigua como en la actual, salvo que la página declare un requisito más limitado. En otras plataformas, siga sus convenciones nativas de rutas, shell, variables de entorno y opciones. Una página compartida solo es válida cuando la sintaxis de comando mostrada es realmente portable. ## Crear páginas para los otros nombres y los subcomandos de un comando Cree las páginas de alias con la herramienta auxiliar de alias del repositorio, cuando exista. Indique que el comando es un alias, incluya un enlace a la información de la fuente original y proporcione un ejemplo que abra la página de referencia del comando original. Mantenga sincronizadas las páginas de alias traducidas mediante la misma herramienta auxiliar, en lugar de editar de forma independiente su estructura generada. En los comandos con subcomandos, mencione en la descripción principal los subcomandos representativos que tengan páginas separadas. Asigne a cada subcomando documentado su propia página con un nombre separado por guiones e incluya un ejemplo que abra la referencia del subcomando correspondiente. No sobrecargue la página principal con flujos de trabajo detallados de subcomandos que correspondan a sus propias páginas. ## Traducir la página sin cambiar sus comandos ni su estructura Traduzca solo después de que exista la página en inglés. Mantenga la misma estructura de ejemplos, la ruta de plataforma, los comandos y los marcadores de posición. No cambie los dominios reservados para ejemplos y mantenga las palabras de los marcadores de posición en el idioma de origen cuando lo exija la política del repositorio. Aplique las reglas de redacción específicas de cada configuración regional en lugar de copiar mecánicamente la gramática inglesa. Por ejemplo: - El chino separa el texto latino y los números del texto chino con espacios y usa signos de puntuación de ancho completo. - El francés usa descripciones de ejemplos en tercera persona y un espacio antes de los signos de puntuación que lo requieran. - El español usa descripciones en tercera persona y los términos técnicos localizados preferidos. - El portugués brasileño y el europeo usan descripciones en tercera persona. - El indonesio usa la forma concisa de descripción de comandos sin prefijos verbales innecesarios. Valide la página traducida con las mismas comprobaciones estructurales que la fuente en inglés. ## Revisar la página con el verificador antes de que la vea una persona Ejecute el linter de páginas del repositorio sobre el archivo modificado antes de solicitar la revisión humana. Use un lint del árbol completo solo cuando lo exija el cambio o la política del repositorio. Revise la página para comprobar: - que el título y el nombre de archivo coincidan; - que la descripción en bloque de cita sea breve y haya un enlace de información válido; - que haya cinco ejemplos preferidos y no más de ocho; - que las descripciones estén en modo imperativo y las líneas en blanco sean correctas; - que las formas de las opciones estén verificadas y se usen marcadores de posición con llaves dobles; - que el directorio de plataforma sea correcto y se use la sintaxis nativa; - que los ejemplos de ayuda y versión ocupen las últimas posiciones cuando se incluyan; - que no haya formato decorativo; - que se respeten las reglas específicas de la configuración regional en las traducciones; - que haya un salto de línea final. Use los scripts de mantenimiento del repositorio, cuando estén disponibles, para actualizaciones mecánicas de títulos, enlaces, alias, referencias cruzadas y comandos. Dé prioridad al modo dry-run antes de realizar un cambio amplio mediante scripts. ## Dar a la IA el manual y páginas parecidas antes de escribir Reduzca el coste de la IA y los ciclos de corrección aportando pruebas antes de redactar. Incluya la salida de la ayuda o del manual del comando, señale dos o tres páginas similares aprobadas y proporcione la plantilla de la página, en lugar de pedir al agente que recuerde las convenciones. Compruebe primero si existe una página. Agrupe las solicitudes de páginas relacionadas cuando compartan contexto, pero revise cada página de forma independiente. Redacte cinco o seis ejemplos de gran utilidad en lugar de completar el límite de ocho ejemplos. Ejecute el linter antes de la revisión humana para que los errores de formato no consuman la atención de quien revisa. El ahorro de costes debe proceder de mejores entradas, la reutilización y la validación determinista, nunca de omitir la verificación de fuentes ni de reducir la calidad de la página.