Consejos para un impresionante archivo léame (y por qué es importante)
Nosotros, los desarrolladores, son muy buenos con el código y todos los detalles de nuestros proyectos. Pero algunos de Nosotros (incluido yo) carecemos de habilidades blandas incluso en la comunidad en línea.,
Un desarrollador pasaría una hora ajustando el relleno y el margen de un solo botón. Pero no tendría 15 minutos para el Archivo Readme de descripción del proyecto.
espero que la mayoría de ustedes readme.md el archivo es y para qué se utiliza. Pero para los novatos aquí voy a tratar de explicar lo que es exactamente.
Readme.md?
README (como su nombre indica: «Léeme») es el primer archivo que se debe leer al iniciar un nuevo proyecto., Es un conjunto de información útil sobre un proyecto y una especie de manual. Es el primer archivo que Github o cualquier sitio de alojamiento de Git mostrará cuando alguien abra tu repositorio..
Como se puede ver claramente aquí el archivo Léame.md archivo está en la raíz del repositorio y se muestra automáticamente por github a continuación el directorio del proyecto.
y la extensión.md viene de una palabra: markdown., Es un lenguaje de marcado para el formato de texto. Al igual que HTML, es un lenguaje de marcado para hacer que nuestros documentos sean presentables.
Aquí hay un ejemplo de un archivo markdown y cómo se renderiza en github en realidad. Yo uso VSCode aquí para la vista previa que muestra una vista previa de los archivos markdown simultáneamente.
Aquí es un oficial de Github hoja de trucos para las Rebajas de formato si necesita habitar en la profundidad de la lengua.
ahora hablemos de negocios., Pasaste horas en un proyecto, lo hiciste público en GitHub y quieres personas / reclutadores / colegas / (Ex?) ver su proyecto. ¿Realmente crees que entrarían en root/src/app/main.js para ver esa hermosa lógica tuya? ¿En serio?
ahora que tengo su atención, veamos cómo abordar esto.
generar documentación para sus componentes
Además del readme de su proyecto, la documentación de sus componentes es crucial para una base de código comprensible. Hace que sea mucho más fácil reutilizar componentes y mantener su código., Utilice herramientas como Bit (Github) para generar automáticamente la documentación de los componentes compartidos en bit.dev
¡describa su proyecto! (TL; DR)
Escribe una buena descripción de tus proyectos. Solo como guía, puede formatear su descripción en los siguientes temas: –
- Título (una imagen de título también si es posible Edit edítelos en canva.,com si no eres diseñador gráfico.)
- Descripción(describa por palabras e imágenes por igual)
- Demo(imágenes, enlaces de Video, enlaces de demostración en vivo)
- tecnologías utilizadas
- Gotchas especiales de sus proyectos (problemas que enfrentó, elementos únicos de su proyecto)
- Descripción técnica de su proyecto como – Instalación, Configuración, cómo contribuir.
vamos a profundizar en los tecnicismos
voy a usar este proyecto mío como referencia, que creo que tiene uno de los archivos readme más hermosos que he escrito e incluso me he encontrado., Usted puede comprobar fuera de el código del archivo «Readme».md archivo aquí:-
Utilice el icono de lápiz para mostrar el código markdown :-
AGREGAR IMÁGENES! ¡POR FAVOR!
Usted puede tener una memoria fotográfica, pero sus lectores pueden necesitar algunas fotografías reales de la demostración de su proyecto.
por ejemplo, hice un proyecto de solitario y agregué imágenes como descripción en el readme.,
Now you may want to add a video description of your projects too. Just like I did. BUT… Github doesn’t let you add a video to the readme… So… So what?
…WE USE GIFS
los Gifs caen en la categoría de imágenes y github te permite tenerlos en tu readme.
La insignia de Honor
Las insignias en su readme le dan al espectador cierta sensación de autenticidad., Usted puede obtener personalizar/usa regularmente escudos(insignias) para su repositorio de:- https://shields.io
Usted puede obtener personalizada escudos, tales como el número de estrellas en la repo de código y los indicadores porcentuales demasiado.
agregue una Demostración en vivo
si es posible, aloje su proyecto y configure una demostración en ejecución. Después de eso, enlace esta DEMO a su README., No tienes idea de cuántas personas podrían terminar jugando con tus proyectos. Y reclutador simplemente amor proyectos en vivo. Muestra que tus proyectos no son solo un volcado de código en github y que realmente hablas en serio.
puede utilizar Hipervínculos en el archivo Léame. Así que dar un enlace de demostración en vivo justo debajo de la imagen del título.
Usar formato de Código
Markdown le da la opción de formatear el texto como código., Así que no escriba código como texto plano en lugar de usar ` (Tilde) para envolver el código dentro del formato de código como tal- var a = 1;
Github también le da la opción de especificar el idioma en el que está escrito el código para que pueda usar el resaltado de texto específico para hacer que el código sea más legible. Para hacer esto use
«{language-extension}<space>{Code block Inside}«
{ « }- la tilde Triple se usa para el código multilínea y también le permite especificar el idioma del bloque de código.,
With Language Highlighting:-
Without Langage Highlighting:-
Use of HTML
Yes, you can use HTML inside. Not all the features though. But most of it., Aunque usted debe atenerse a markdown solamente pero, algunas características como centrar imágenes y texto en el readme solo es posible por HTML.
Deja una respuesta