Un archivo README debería ayudar a un nuevo lector a dar el primer paso útil. No es necesario explicar todos los detalles de la implementación antes de que puedan decir qué hace el proyecto o si es relevante para ellos.

Liderar con el resultado

Describe qué hace el proyecto, para quién es y sus límites importantes. Un ejemplo concreto es más útil que una lista de adjetivos. Coloque una captura de pantalla funcional o un resultado de muestra cerca de la parte superior cuando ayude a explicar el propósito.

Luego indique los requisitos previos: sistema operativo, versión de ejecución y servicios requeridos. Distinga las integraciones opcionales de lo que se necesita para comenzar. No permita que el lector descubra un requisito esencial a mitad de la instalación.

Ofrezca un camino completo hacia el éxito

Escriba los pasos de configuración en el orden en que deben realizarse. Explique dónde deben ejecutarse los comandos y cómo se ve un resultado exitoso. Utilice la configuración del marcador de posición con claridad y nunca incluya credenciales reales en el ejemplo.

Pruebe las instrucciones desde un punto de partida limpio o equivalente. Un comando que funciona sólo porque su máquina tiene instalada una herramienta no documentada es una falta de documentación. Mantenga las variaciones opcionales debajo de la ruta admitida más simple.

Haga que el siguiente paso sea fácil de encontrar

Agregue los comandos comunes para ejecutar, verificar y actualizar el proyecto. Enlace a documentación más profunda en lugar de colocar cada tema especializado en la sección de apertura. Incluya el lugar admitido para informar problemas y la licencia cuando corresponda.

Utilice MeatPad para editar el archivo README junto a los archivos del proyecto, luego verifique su Markdown renderizado en el destino. Siga enlaces e inspeccione imágenes con las rutas reales del repositorio. Cuando cambie la configuración, actualice el archivo README con el mismo cambio para que las instrucciones de primera ejecución describan la versión que reciben las personas.

Fuentes y detalles del producto.

Comience con una nota. MeatPad proporciona notas, Markdown y archivos de proyecto en un espacio de trabajo local en tu Mac, sin necesidad de tener una cuenta.

Explorar MeatPad →