Sysadmin University: Cómo escribir un archivo README

El archivo README es el que normalmente ve cuando descarga el código fuente para compilarlo e instalarlo en su sistema. Esta es (con suerte) una guía que lo ayuda a comprender, instalar y configurar fácilmente su nueva aplicación. Si bien esta es la intención del archivo, en realidad no hay estándares establecidos sobre qué incluir en él. En este artículo, le daré mi opinión y preferencias para el contenido ideal del archivo README, y le daré dos plantillas que puede usar para crear las suyas propias.

No soy un programador empedernido, pero para grupos de secuencias de comandos o aplicaciones web, podría escribir en PHP, Perl o secuencias de comandos de shell. Siempre proporciono un archivo LÉAME para que cualquier persona que use o apoye mi aplicación pueda comprenderla mejor y su función. .

Puede escribir su README en texto sin formato, rebajas o cualquier otro estilo de texto que desee. Prefiero las rebajas, texto sin formato y HTML, en ese orden. Me gusta que se destaque porque es fácil de usar y puede crear un documento atractivo con un mínimo de peculiaridad de codificación y sin un editor sofisticado.

Índice

Título del Proyecto

Desde el punto de vista del marketing, los títulos de sus proyectos deben ser claros y comunicar claramente su función sin descripciones ni juegos de palabras innecesarios. Si es un editor de texto, llámalo así, al menos después de dos puntos.

Por ejemplo, si estoy creando un proyecto de aplicación web para ayudar a los ingenieros de capacidad y rendimiento a administrar cientos de servidores, entonces un buen título podría ser "CapPlanMan: la herramienta de administración de planificación de capacidad en lugar de algo como "Vaso medio lleno: el planificador de capacidad". ." No voy a ahondar en la psicología del naming, pero creo que se puede ver la idea aquí.

La descripcion

La sección Descripción describe el proyecto, programa o aplicación en 30 palabras o menos. Este es un resumen de lo que la aplicación hace por el usuario, la tecnología que utiliza y el propósito del proyecto. Aquí un ejemplo:

Esta descripción es básicamente su "sin ascensor" para el proyecto. Es un breve resumen de lo que es tu proyecto y lo que hace sin farsa ni propaganda.

condiciones previas

Si su proyecto requiere aplicaciones o configuraciones especiales, las ubicará en esta sección. No se necesita mucha explicación aquí. Enumere los requisitos, paquetes, configuraciones y consideraciones de espacio en disco.

Agregue también cualquier requisito especial para los permisos del sistema de archivos, los permisos de la base de datos, etc.

Instalación

Esta sección describe cómo instalar sus archivos de proyecto. Opcionalmente, puede crear un archivo INSTALL.md y consultarlo aquí si las instrucciones son más largas que unos pocos párrafos. Pero si puede mantenerlo conciso, inclúyalo aquí.

Asegúrese de incluir todos los pasos aquí o en el archivo INSTALL.md. No hay nada más frustrante que pasar horas resolviendo problemas con el script de instalación de otra persona, así que elimine la molestia de sus usuarios.

Usar

Incluya todas las notas de uso aquí. Proporcione sintaxis genérica y ejemplos.

$ ./install.sh -uroot [email protected]$$w0rd 

Esta entrada puede ser tan simple como la anterior, o puede proporcionar varios escenarios de ejemplo que describan las diferentes opciones disponibles.

contribuyendo

La sección Contribuir brinda a los contribuyentes potenciales una forma de contactar al autor (es) y enviar erratas o mejoras al proyecto.

Es una parte necesaria de cualquier proyecto comunitario. Todos se sienten empoderados si pueden participar en el desarrollo de un proyecto. También agrega valor el hecho de que otras personas contribuyan, ya que significa que el proyecto tiene valor fuera de su alcance original.

Autores

Incluir todos los autores de un proyecto. Opcionalmente incluya una dirección de correo electrónico.

Licencia

Es una práctica común especificar una licencia. Hay muchos para que elijas. Si necesita ayuda para decidir, esta herramienta le puede dar algunos consejos. Si está creando código para el trabajo, asegúrese de consultar con su departamento legal para obtener sus comentarios y aprobación.

Gracias

Los agradecimientos son reconocimientos a las personas que han proporcionado recursos para su proyecto. Asegúrate de mencionarlos aquí.

Conclusión

Si escribe y hace públicos proyectos de software, debe incluir un documento LÉAME para acompañarlo. No deje a sus usuarios potenciales a la deriva en cuanto a cómo instalar y usar su software. Sé conciso. Use algún tipo de formato estándar para que los lectores entiendan lo que están viendo. A continuación hay dos enlaces a plantillas. Siéntase libre de usarlos, mis ejemplos, o use las pautas anteriores para crear uno propio.

-A Modelo LÉAME.md en GitHub desde Soporte morado

-LÉAME 101 por makeareadme.com

Artículos de interés

Subir