Tippek egy fantasztikus readme file (s hogy ez miért fontos)

Jan 19, 2020 · 6 min olvassa el a

Mi, a fejlesztők, nagyon jó a kód, meg minden részletet el a projektek. De néhányan közülünk (engem is beleértve) hiányzik a puha készségek még az online közösség.,

egy fejlesztő egy órát töltene egyetlen gomb párnázásának és margójának beállításával. De nem kímélne 15 percet a README fájl projektleírásához.

remélem, hogy a legtöbben már tudják, mi a readme.md a fájl az, és mire használják. De az újoncok itt megpróbálom elmagyarázni, hogy pontosan mi az.

mi az a Readme.md?

README (ahogy a neve is sugallja:” read me”) az első fájl, amelyet el kell olvasni egy új projekt indításakor., Ez egy sor hasznos információ egy projektről és egy kézikönyvről. Ez az első fájl Github vagy bármely Git hosting oldalon jelenik meg, ha valaki megnyitja a repository..

ahogy jól látható itt Readme.md a fájl a tároló gyökerében található, és a github automatikusan megjelenik a projektkönyvtár alatt.

és a.mdkiterjesztés egy szóból származik: markdown., Ez egy jelölő nyelv a szöveg formázásához. Csakúgy, mint a HTML, ez egy jelölő nyelv, hogy dokumentumainkat bemutathatóvá tegyük.

itt egy példa egy markdown fájlra, valamint arra, hogy valójában hogyan jelenik meg a GitHubon. Itt használom a VSCode-ot az előnézethez, amely egyszerre mutatja a markdown fájlok előnézetét.

Itt van egy hivatalos Github puskát az Árleszállítás formátum, ha kell lakik mélyen a nyelv.

most beszéljünk az üzletről., Órákat töltött egy projekten, nyilvánosságra hozta a Githubon, és embereket/toborzókat/kollégákat / (Ex?) lásd a projektet. Tényleg azt hiszed, hogy bemennek a root/src/app/main.js – ba, hogy megtekintsék a gyönyörű logikádat? Komolyan?

most, hogy felkeltettem a figyelmét, nézzük meg, hogyan kell kezelni ezt.

dokumentáció készítése a komponensekhez

a projekt readme-ján kívül az összetevők dokumentálása elengedhetetlen egy érthető kódbázishoz. Ez sokkal könnyebbé teszi az összetevők újrafelhasználását és a kód fenntartását., Használjon olyan eszközöket, mint a Bit (Github) a biten megosztott összetevők dokumentációjának automatikus létrehozásához.dev

példa: a biten megosztott összetevők keresése.dev

írja le a projektet! (TL; DR)

írj egy jó leírást a projektek. Csak az irányelvek, akkor formázza a leírást a következő témákban: –

  • cím (a cím kép is, ha lehetséges…szerkeszteni őket canva.,com ha nem egy grafikus.)
  • leírás (szavakkal és képekkel egyaránt leírva)
  • Demo (képek, videó linkek, élő Demo linkek)
  • használt technológiák
  • speciális Gotchas a projektek (problémák szembesültek, egyedi elemei a projekt)
  • a projekt technikai leírása, mint – telepítés, beállítás, Hogyan kell hozzájárulni.

merüljünk mélyen a technikákba

ezt az egyik projektemet referenciaként fogom használni, amely szerintem az egyik legszebb readme fájl, amelyet írtam, sőt találkoztam., Akkor nézd meg a kódot a Readme.md fájl itt:-

használja a ceruza ikont a markdown kód megjelenítéséhez :-

képek hozzáadása! Kérlek!

lehet, hogy fényképes memóriája van, de az olvasóknak szüksége lehet néhány tényleges fényképre a projekt demójáról.

például készítettem egy pasziánsz projektet, és képeket adtam hozzá leírásként a readme-ben.,

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

HAHA… Got ya Github.,

a GIF-ek a képek kategóriájába tartoznak, a github pedig lehetővé teszi számukra, hogy a readme-n legyenek.

A Becsületjelvény

jelvények a readme – n némi hitelességet adnak a nézőnek., Lehet egyéni/rendszeresen használt pajzsok(jelvények) a repository-ból:- https://shields.io

lehet kapni, személyre szabott pajzs, mint a csillagok száma a repo, valamint kód százalékos mutatók is.

Add a Live Demo

ha lehetséges, kap a projekt házigazdája, és hozzanak létre egy futó demo. Ezt követően LINK ezt a demót a README., Fogalmad sincs, hány ember lehet a végén játszik körül a projektek. És a toborzó csak szereti az élő projekteket. Ez azt mutatja, hogy a projektjeid nem csak a githubra rakott kóddugók, és te tényleg az üzletre gondolsz.