Vytvořte návrhy README
pro dobrý README
každý projekt je jiný, takže zvažte, která z těchto sekcí se vztahuje na vaše. Sekce použité v šabloně jsou návrhy pro většinu open source projektů. Mějte také na paměti, že zatímco README může být příliš dlouhý a podrobný, příliš dlouhý je lepší než příliš krátký. Pokud si myslíte, že vaše README je příliš dlouhá, zvažte využití jiné formy dokumentace spíše než vyříznutí informací.
Name
Vyberte si vlastní vysvětlující název projektu.,
popis
dejte lidem vědět, co váš projekt dokáže konkrétně. Poskytnout kontext a přidat odkaz na všechny referenční návštěvníci mohou být obeznámeni s. Zde lze také přidat seznam funkcí nebo podsekci pozadí. Pokud existují alternativy k vašemu projektu, je to dobré místo pro seznam rozlišujících faktorů.
odznaky
u některých READMEs můžete vidět malé obrázky, které předávají metadata, například zda všechny testy procházejí projektem. Můžete použít štíty přidat některé do README. Mnoho služeb má také pokyny pro přidání odznaku.,
vizuální
V závislosti na tom, co děláte, může být dobré zahrnout screenshoty nebo dokonce video (často uvidíte GIF spíše než skutečná videa). Nástroje jako ttygif mohou pomoci, ale podívejte se na asciinema pro sofistikovanější metodu.
instalace
v rámci konkrétního ekosystému může existovat běžný způsob instalace věcí, jako je použití příze, NuGet nebo Homebrew. Zvažte však možnost, že kdokoli čte váš README, je nováček a chtěl by více vedení., Výpis konkrétních kroků pomáhá odstranit nejednoznačnost a přiměje lidi, aby váš projekt používali co nejrychleji. Pokud běží pouze v určitém kontextu, jako je konkrétní verze programovacího jazyka nebo operační systém nebo má závislosti, které je třeba nainstalovat ručně, přidejte také podsekci požadavků.
použití
použijte příklady liberálně a zobrazte očekávaný výstup, pokud je to možné. Je užitečné mít inline nejmenší příklad použití, které můžete prokázat, a zároveň poskytuje odkazy na sofistikovanější příklady, pokud jsou příliš dlouhé, aby rozumně zahrnout do README.,
podpora
řekněte lidem, kam mohou jít o pomoc. Může to být jakákoli kombinace sledovače problémů, chatovací místnosti, e-mailové adresy atd.
Roadmap
Pokud máte v budoucnu nápady na vydání, je dobré je uvést do seznamu README.
uveďte, zda jste otevřeni příspěvkům a jaké jsou vaše požadavky na jejich přijetí.
pro lidi, kteří chtějí provést změny ve vašem projektu, je užitečné mít nějakou dokumentaci o tom, jak začít., Možná existuje skript, který by měli spustit, nebo některé proměnné prostředí, které musí nastavit. Aby tyto kroky explicitní. Tyto pokyny by také mohly být užitečné pro vaše budoucí já.
můžete také dokumentovat příkazy pro vložení kódu nebo spuštění testů. Tyto kroky pomáhají zajistit vysokou kvalitu kódu a snížit pravděpodobnost, že změny nechtěně něco zlomí. Mít pokyny pro spuštění testů je zvláště užitečné, pokud vyžaduje externí nastavení, například spuštění serveru Selenium pro testování v prohlížeči.,
autoři a uznání
ukažte své uznání těm, kteří do projektu přispěli.
Licence
pro open source projekty řekněte, jak je licencován.
stav projektu
Pokud jste vyčerpali energii nebo čas pro svůj projekt, vložte do horní části README poznámku, že vývoj se zpomalil nebo úplně zastavil. Někdo se může rozhodnout rozvětvit váš projekt nebo dobrovolně vstoupit jako správce nebo majitel, což umožňuje vašemu projektu pokračovat. Můžete také výslovně požádat správce.