Haga un README
sugerencias para un buen README
cada proyecto es diferente, así que considere cuál de estas secciones se aplica al suyo. Las secciones utilizadas en la plantilla son sugerencias para la mayoría de los proyectos de código abierto. También tenga en cuenta que si bien un README puede ser demasiado largo y detallado, demasiado largo es mejor que demasiado corto. Si cree que su README es demasiado largo, considere utilizar otra forma de documentación en lugar de cortar la información.
Name
elija un nombre auto-explicativo para su proyecto.,
Descripción
deje que la gente sepa lo que su proyecto puede hacer específicamente. Proporcione contexto y agregue un enlace a cualquier referencia con la que los visitantes no estén familiarizados. Una lista de características o una subsección de fondo también se puede agregar aquí. Si hay alternativas a su proyecto, este es un buen lugar para enumerar los factores diferenciadores.
insignias
en algunos READMEs, puede ver pequeñas imágenes que transmiten metadatos, como si todas las pruebas están pasando o no para el proyecto. Puede usar escudos para agregar algunos a su README. Muchos servicios también tienen instrucciones para agregar una insignia.,
visuales
dependiendo de lo que esté haciendo, puede ser una buena idea incluir capturas de pantalla o incluso un video (verá con frecuencia GIF en lugar de videos reales). Herramientas como ttygif pueden ayudar, pero echa un vistazo a Asciinema para un método más sofisticado.
instalación
dentro de un ecosistema en particular, puede haber una forma común de instalar cosas, como usar Yarn, NuGet o Homebrew. Sin embargo, considere la posibilidad de que quien está leyendo su README es un novato y le gustaría más orientación., Enumerar pasos específicos ayuda a eliminar la ambigüedad y hace que las personas usen tu proyecto lo más rápido posible. Si solo se ejecuta en un contexto específico como una versión de lenguaje de programación o sistema operativo en particular o tiene dependencias que deben instalarse manualmente, también agregue una subsección de requisitos.
Usage
Use ejemplos generosamente y muestre la salida esperada si puede. Es útil tener en línea el ejemplo más pequeño de uso que pueda demostrar, mientras proporciona enlaces a ejemplos más sofisticados si son demasiado largos para incluirlos razonablemente en el README.,
Support
Dile a las personas a dónde pueden ir para obtener ayuda. Puede ser cualquier combinación de un rastreador de problemas, una sala de chat, una dirección de correo electrónico, etc.
Hoja de Ruta
Si tiene ideas para lanzamientos en el futuro, es una buena idea enumerarlas en el README.
Contributing
indique si está abierto a contribuciones y cuáles son sus requisitos para aceptarlas.
para las personas que quieren hacer cambios en su proyecto, es útil tener alguna documentación sobre cómo comenzar., Tal vez hay un script que deben ejecutar o algunas variables de entorno que necesitan establecer. Haz que estos pasos sean explícitos. Estas instrucciones también podrían ser útiles para su yo futuro.
también puede documentar comandos para pelar el código o ejecutar pruebas. Estos pasos ayudan a garantizar una alta calidad del código y reducen la probabilidad de que los cambios rompan algo inadvertidamente. Tener instrucciones para ejecutar pruebas es especialmente útil si requiere una configuración externa, como iniciar un servidor Selenium para realizar pruebas en un navegador.,
los autores y agradecimientos
muestran su agradecimiento a quienes han contribuido al proyecto.
License
para proyectos de código abierto, diga cómo se licencia.
estado del proyecto
si se ha quedado sin energía o tiempo para su proyecto, ponga una nota en la parte superior del README diciendo que el desarrollo se ha ralentizado o detenido por completo. Alguien puede optar por bifurcar su proyecto o ofrecerse como voluntario para intervenir como mantenedor o propietario, lo que permite que su proyecto continúe. También puede hacer una solicitud explícita para los mantenedores.