Tipy na úžasné readme souboru (a proč je to důležité)

Jan 19, 2020 · 6 min číst

My, vývojáři, jsou velmi dobré s kódem a všechny minute informace z našich projektů. Ale někteří z nás (včetně mě) postrádají měkké dovednosti i v online komunitě.,

vývojář by strávil hodinu úpravou polstrování a okraje jediného tlačítka. Ale nešetřil 15 minut pro popis projektu README souboru.

doufám, že většina z vás již víte, co je readme.md soubor je a k čemu se používá. Ale pro nováčky se pokusím vysvětlit, co to přesně je.

Co je Readme.md?

README (jak název napovídá: „read me“), je první soubor, jeden by měl číst, když začíná nový projekt., Je to soubor užitečných informací o projektu a jakési příručce. Jedná se o první soubor GitHub nebo jakýkoli hostingový web Git se zobrazí, když někdo otevře úložiště..

Jak můžete vidět tady Readme.md soubor je v kořenovém úložišti a automaticky se zobrazí github pod adresáři projektu.

a.mdrozšíření pochází ze slova: markdown., Je to značkovací jazyk pro formátování textu. Stejně jako HTML je to značkovací jazyk, který umožňuje prezentovat naše dokumenty.

zde je příklad souboru markdown a jak se ve skutečnosti vykresluje na Githubu. Používám zde VSCode pro náhled, který zobrazuje náhled souborů markdown současně.

Tady je oficiální Github tahák formátu Markdown, pokud potřebujete bydlet hluboko do jazyka.

Nyní pojďme mluvit o podnikání., Strávili jste hodiny na projektu, zveřejnili jste ho na Githubu a chcete lidi / náboráře / kolegy / (Ex?) Viz váš projekt. Opravdu si myslíte, že by šli do root/src/app/main.js, aby viděli vaši krásnou logiku? Vážně?

Nyní, když mám vaši pozornost, podívejme se, jak to řešit.

Vytváření dokumentace pro vaše komponenty

kromě vašeho projektu readme, dokumentování vašich komponent je rozhodující pro srozumitelné codebase. To usnadňuje opětovné použití komponent a udržování kódu., Použijte nástroje jako Bit (Github) k automatickému generování dokumentace pro komponenty sdílené na bit.dev

Příklad: hledání sdílené složky na Bit.dev

popište svůj projekt! (TL; DR)

napište dobrý popis vašich projektů. Jen pro pokyny můžete svůj popis naformátovat do následujících témat: –

  • Title(pokud je to možné, také titulní obrázek … upravte je na canvě.,com pokud nejste Grafik.)
  • Popis(Popsat slovy a obrázky a podobně)
  • Demo(Obrázky, Videa, odkazy, Demo odkazy)
  • Použité Technologie
  • Speciální Gotchas vaše projekty (Problémy, kterým čelí jste, unikátní prvky vašeho projektu)
  • Technický Popis projektu jako – Instalace, Nastavení, Jak přispět.

Pojďme se ponořit hluboko do technické aspekty

budu používat tento jeden projekt jako referenční, což si myslím, že má jednu z nejkrásnějších soubory readme, které jsem napsal, a dokonce narazil na., Můžete se podívat na kód v souboru Readme.md soubor zde:

Použijte ikonu tužky ukázat markdown kód :-

PŘIDAT OBRÁZKY! Prosím!

můžete mít fotografickou paměť, ale vaši čtenáři mohou potřebovat nějaké skutečné fotografie demo vašeho projektu.

například jsem vytvořil projekt solitaire a přidal obrázky jako popis v 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

HAHA… Got ya Github.,

GIF spadají do kategorie obrázků a github vám umožní mít je na readme.

odznak cti

odznaky na vašem readme dávají divákovi pocit autenticity., Můžete získat vlastní/pravidelně používají štíty(odznaky) pro vaše úložiště z:- https://shields.io

můžete získat osobní štíty, jako je počet hvězd na repo a kód procentního ukazatele.

přidejte živé Demo

Pokud je to možné, nechte svůj projekt hostit a nastavte běžící demo. Poté propojte toto DEMO s README., Nemáte tušení, kolik lidí by mohlo skončit hrát si s vašimi projekty. A náborář prostě miluje živé projekty. Ukazuje, že vaše projekty nejsou jen výpisem kódu, který leží na GitHubu,a ve skutečnosti podnikáte.

můžete použít hypertextové Odkazy v Readme. Dejte tedy živý Demo odkaz těsně pod titulním obrázkem.

použijte kód Formating

Markdown vám dává možnost formátovat text jako kód., Takže se nemusíte psát kód, jako prostý text místo toho použít ` (Tilda) zabalit kód uvnitř formátování kódu jako takového- var a = 1;

Github také vám dává možnost určit jazyk, kód je napsán tak, že to může použít specifické zvýraznění textu, aby se kód lépe čitelný. K tomu použít

„{jazyk-přípona}<místo>{blok Kódu Uvnitř}„

{ „ }- Trojité vlnovky se používá pro multi-řádku kódu a to také umožňuje určit jazyk blok kódu.,

With Language Highlighting:-

Without Langage Highlighting:-

Use of HTML

Yes, you can use HTML inside. Not all the features though. But most of it., I když byste se měli držet pouze markdown, ale některé funkce, jako je Centrování obrázků a textu v readme, jsou možné pouze HTML.