Documentación del proyecto

Debe contener todos los aspectos que el promotor necesita conocer y que no puede recibir directamente del código. Estos incluyen lo que se debe y no se debe hacer en el desarrollo, instrucciones completas de despliegue, descripciones de integración externa, etc. Este artículo te guiará en la creación de un archivo README potente, bonito y legible para tu proyecto. proyecto.

En las guías de github se puede encontrar una buena introducción para una documentación de proyecto bien preparada: https://guides.github.com/features/wikis/. En él se establece que "README debe contener únicamente la información necesaria para que los desarrolladores puedan empezar a utilizar el proyecto y contribuir a él".

Teniendo esto en cuenta, vamos a presentar una lista de componentes y buenas prácticas que seguimos en Codest para crear la documentación de un proyecto.

Introducción rápida

- Título del proyecto: esto es imprescindible en todo README.

- Insignias de estadosi utiliza mediciones externas de la calidad del código, pruebas automatizadas u otras herramientas, el principio del documento es un buen lugar para mostrar a los demás si funcionan.

- DescripciónIncluye algunas frases sobre el proyecto para describir rápidamente su objetivo principal y su función.

Índice

Una lista de contenidos puede ser útil para archivos de documentación largos, pero si su README es bastante conciso entonces no es necesario.

Información general

- Acerca de la seccióndescripción más detallada del proyecto: puede incluir información sobre los usuarios, sus funciones, algunos casos más confusos, capturas de pantalla, etc.

- Maquetasun lugar para enlaces a recursos de maquetas UI/UX, si los hay.

• Otra información como Acceso a los servidores o Integración con API externasEjemplos: dirección url de una instancia de ensayo, credenciales de acceso compartidas no sensibles, enlaces a documentación, instrucciones, etc.

Instalación

- RequisitosRequisitos previos que deben cumplirse antes de iniciar la configuración de una aplicación, por ejemplo, la instalación de herramientas externas.

- Configuracióninstrucciones paso a paso para poner en marcha el proyecto.

- Ajustes: describen dónde se almacenan los ajustes locales y proporcionan instrucciones sobre cómo recibir tus propios ajustes.

- Configuración local: si hay algunos casos para la configuración local, este es un buen lugar para una explicación.

Desarrollo

Esta sección es un lugar ideal para instrucciones como desarrollo de características, corrección de errores, hotfixes, características comunes, pruebas, guías de estilo, organización del código, otras herramientas de desarrollo utilizadas en el proyecto (por ejemplo, guards o dockers), etc. No olvides mencionar todas las normas que cada equipo miembro debe saber.

Despliegue

Proporcione instrucciones claras paso a paso para cada entorno y todo lo que "conviene saber" al realizar la implantación.

Otras ideas para secciones separadas

- Documentación API

- Cambios

- Recursos externosUn lugar para todo tipo de enlaces que puedan ser útiles.

- Pila de aplicaciones: una lista de la pila de aplicaciones que utilizamos en el proyecto - puede contener una breve descripción y el nombre del proveedor.

Equipo

Es discutible si es necesario mostrar los miembros actuales del equipo del proyecto (github proporciona la lista completa de colaboradores por defecto), pero siempre es agradable ver tu nombre como uno de los autores de un proyecto. Si lo haces, mantenlo lo más actualizado posible.

Unas palabras finales

Recuerda: cada proyecto es único y también lo es su documentación. No hay una gran solución para escribir un README. Basta con seguir los consejos generales, y lo más importante es acordarse siempre de la refactorización, que también conecta con el LÉAME. Siempre es una buena idea mirar el documento en su conjunto y replantearlo si algo necesita ser mostrado de una manera diferente.

Una cosa más: las "instrucciones" son clave, así que escríbelas mucho. Gracias.

Más información:

• Principio abierto-cerrado. ¿Tengo que usarlo alguna vez?
• ¿Cómo escribir un código bueno y de calidad?
• Vuelendar. Un nuevo proyecto de Codest basado en Vue.js