Cómo escribir un README
Cómo escribir un archivo README
Si las personas no saben por qué existe tu proyecto, no lo usarán, Si las personas no descifran cómo instalar tu código, no lo usarán. Si las personas no descifran cómo usar tu código, no lo usarán. WriteTheDocs
Anatomía de un README
Éstos son los nombres de algunas secciones comunes en los archivos README que debes considerar agregar:
- Descripción:
- Describe en unas cuantas líneas para qué sirve tu proyecto. Trata de ser conciso.
- Tabla de contenido:
- Si tu documentación es extensa, lo mejor es que incluyas un índice para mejorar la navigabilidad.
- Instalación o Getting Started:
- Los pasos necesarios para preparar el ambiente antes de usar tu código
- Ejemplos o Uso:
- Incluye algunos ejemplos sobre cómo utilizar tu proyecto
- Preguntas y Respuestas Frecuentes (FAQs)
- Si recibes constantemente las mismas preguntas sobre tu proyecto, tal vez sea mejor incluir esta sección para que los usuarios no pierdan tiempo.
- Licencia:
- Siempre elige una licencia adecuada para tu proyecto.
- En Github, si no eliges una licencia por defecto conservas todos los derechos sobre tu proyecto pero siempre es mejor ser explícito al respecto.
- Visita Choose a License para aclarar tus dudas
- Bugs conocidos
- Publica los bugs conocidos para ahorrar tiempo a los desarrolladores, que sepan que no es su código el que falla.
- Contribuciones
- Si este es un proyecto open source en esta sección indica cómo es que se deben hacer las contribuciones.
- Acerca del desarrollador
- Escribe un poco sobre quién o quiénes son los desarrolladores de este proyecto. Puedes incluir un enlace a tu página oficial.
Guía
Antes de escribir el archivo README de cualquier proyecto, hazte las siguientes preguntas:
- ¿Cuáles son los pasos necesarios para echar a andar el proyecto?
- ¿Qué cosas debería el usuario tener ya instalado o configurado para poder usar mi proyecto?
- ¿Qué conceptos podrían no ser tan intuitivos o fáciles de entender?
Markdown
Si utilizas Github, recuerda que el lenguaje de marcado preferido por esta plataforma es Markdown.