des Conseils pour un super fichier readme (et pourquoi c’est important)
Nous, les développeurs, sont très bonne avec le code et tous les détails de nos projets. Mais certains d’entre nous (moi inclus) manquent de compétences non techniques, même dans la communauté en ligne.,
un développeur passerait une heure à ajuster le remplissage et la marge d’un seul bouton. Mais n’épargnerait pas 15 minutes pour le fichier Readme de description du projet.
j’espère que la plupart d’entre vous savent déjà ce readme.md le fichier est et à quoi il sert. Mais pour les débutants ici, je vais essayer d’expliquer ce que c’est exactement.
Qu’est-ce qu’un Readme.md?
README (comme son nom l’indique: « read me”) est le premier fichier à lire lors du démarrage d’un nouveau projet., C’est un ensemble d’informations utiles sur un projet et une sorte de manuel. C’est le premier fichier que Github ou n’importe quel site d’hébergement Git affichera lorsque quelqu’un ouvrira votre dépôt..
Comme vous pouvez le voir ici Readme.md fichier est à la racine du référentiel et est automatiquement affichée par github ci-dessous le répertoire du projet.
et l’extension.md vient d’un mot: markdown., C’est un langage de balisage pour le formatage du texte. Tout comme le HTML, c’est un langage de balisage pour rendre nos documents présentables.
Voici un exemple de fichier markdown et comment il s’affiche sur github. J’utilise VSCode ici pour l’aperçu qui montre un aperçu des fichiers markdown simultanément.
Voici un officiel Github feuille de triche pour le format Markdown si vous avez besoin d’habiter en profondeur dans la langue.
Maintenant, nous allons parler des affaires., Vous avez passé des heures sur un projet, vous l’avez rendu public sur GitHub et vous voulez des personnes / recruteurs / collègues / (Ex?) voir votre projet. Pensez-vous vraiment qu’ils iraient dans root/src/app/main.js pour voir votre belle logique? Vraiment?
maintenant que j’ai votre attention, voyons comment aborder cela.
générer de la documentation pour vos composants
en plus du readme de votre projet, la documentation de vos composants est cruciale pour une base de code compréhensible. Il est beaucoup plus facile de réutiliser les composants et de maintenir votre code., Utilisez des outils comme Bit (Github) pour générer automatiquement la documentation des composants partagés sur bit.dev
Décrivez votre projet! (TL;DR)
Ecrivez une bonne description de vos projets. Juste pour les directives, vous pouvez formater votre description dans les rubriques suivantes: –
- Titre (une image de titre aussi si possible Edit modifiez-les sur canva.,com si vous n’êtes pas un graphiste.)
- Description(décrire par des mots et des images)
- Démo(Images, liens vidéo, liens de démonstration en direct)
- Technologies utilisées
- Gotchas spéciaux de vos projets (problèmes rencontrés, éléments uniques de votre projet)
- Description technique de votre projet comme – Installation, Configuration, comment contribuer.
plongeons profondément dans les technicalités
je vais utiliser ce projet comme référence, qui je pense a l’un des plus beaux fichiers readme que j’ai écrits et même rencontré., Vous pouvez vérifier le code de ce fichier.md fichier ici:-
Utilisez l’icône en forme de crayon pour afficher le code markdown :-
AJOUTER des IMAGES! S’il vous PLAÎT!
Vous avez peut-être une mémoire photographique mais vos lecteurs peuvent avoir besoin de photographies réelles de la démo de votre projet.
par exemple, j’ai fait un projet solitaire et ajouté des images en tant que description dans le 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
Les Gifs entrent dans la catégorie des images et github vous permet de les avoir sur votre readme.
L’Insigne D’honneur
Les Insignes sur votre readme donnent au spectateur une certaine sensation d’authenticité., Vous pouvez obtenir personnalisé/régulièrement utilisé des boucliers(badges) pour votre référentiel à partir de:- https://shields.io
Vous pouvez obtenir personnalisé boucliers tels que le nombre d’étoiles sur le repo et le code de pourcentage indicateurs de trop.
ajouter une démo en direct
si possible, hébergez votre projet et configurez une démo en cours d’exécution. Après cela, liez cette démo à votre README., Vous n’avez aucune idée du nombre de personnes qui pourraient finir par jouer avec vos projets. Et le recruteur adore les projets en direct. Cela montre que vos projets ne sont pas seulement un vidage de code sur github et que vous voulez réellement faire des affaires.
Vous pouvez utiliser des liens hypertexte dans votre fichier Readme. Donnez donc un lien de démonstration en direct juste en dessous de l’Image de titre.
utiliser le formatage de Code
Markdown vous donne la possibilité de formater le texte sous forme de code., Donc, n’écrivez pas de code en texte brut utilisez plutôt ` (Tilde) pour envelopper le code dans le formatage du code en tant que tel- var a = 1;
Github vous donne également la possibilité de spécifier la langue dans laquelle le code est écrit afin qu’il puisse utiliser la mise en surbrillance de texte spécifique Pour ce faire, utilisez
« {language-extension}<space>{code block Inside}«
{ « }- Le triple tilde est utilisé pour le code multiligne et vous permet également de spécifier la langue du bloc de code.,
With Language Highlighting:-
Without Langage Highlighting:-
Use of HTML
Yes, you can use HTML inside. Not all the features though. But most of it., Bien que vous ne devriez vous en tenir qu’à markdown, certaines fonctionnalités telles que le centrage des images et du texte dans le fichier readme ne sont possibles que par HTML.
Laisser un commentaire