Las páginas de manual (man pages) son una parte fundamental de la documentación de herramientas en sistemas Unix-like, pero a menudo pueden ser difíciles de navegar y comprender. Julia Evans, en su blog, explora cómo mejorar la usabilidad de las man pages, inspirándose en sus propias experiencias creando hojas de trucos (cheat sheets) para herramientas como tcpdump, git y dig. El objetivo es transformar las man pages en recursos más accesibles y eficientes.
Una de las ideas clave es la inclusión de un “Resumen de opciones” (OPTIONS SUMMARY) al estilo de la página de manual de rsync. En lugar de una larga lista alfabética, este resumen ofrece una descripción concisa de una sola línea para cada opción, seguido de la sección completa de opciones con descripciones detalladas. Otra sugerencia es organizar las opciones por categorías, como se ve en la página de manual de strace, en lugar de simplemente alfabéticamente. Evans incluso experimentó con esta idea para la página de manual de grep, creando una versión categorizada que puede ser útil para usuarios que luchan por recordar el nombre de opciones específicas.
Además de la organización, Evans destaca la importancia de incluir ejemplos prácticos. Inspirándose en las páginas de manual de Perl y en el estilo de OpenBSD, propone la inclusión de secciones tipo “cheat sheet” con ejemplos de sintaxis y uso. La página de manual de curl es un excelente ejemplo, con ejemplos para cada opción que ilustran su uso y a menudo sugieren opciones complementarias. También se menciona la importancia de incluir ejemplos al principio de la página, como lo hizo Evans al trabajar en las páginas de manual de git-add y git rebase.
Finalmente, Evans señala la necesidad de mejorar la navegación dentro de las man pages, especialmente en la terminal. La adición de una tabla de contenidos y enlaces internos, como se implementó en las páginas de manual de Git alojadas en HTML, facilita la exploración de la documentación. En resumen, la mejora de las man pages implica una combinación de organización lógica, ejemplos prácticos y una mejor estructura de navegación, con el objetivo de hacer que la documentación sea más accesible y útil para los usuarios.