Készítsen README
javaslatokat egy jó README
minden projekt más, ezért fontolja meg, hogy ezek közül melyik szakasz vonatkozik a tiédre. A sablonban használt szakaszok javaslatok a legtöbb nyílt forráskódú projekthez. Ne feledje azt sem, hogy míg a README túl hosszú és részletes lehet, a túl hosszú jobb, mint a túl rövid. Ha úgy gondolja, hogy a README túl hosszú, fontolja meg a dokumentáció egy másik formájának használatát, nem pedig az információk kivágását.
Name
válasszon egy önmagyarázó nevet a projekthez.,
leírás
tudassa az emberekkel, hogy mit tehet a projekt kifejezetten. Adja meg a kontextust, majd adjon hozzá egy linket minden olyan hivatkozáshoz, amelyet a látogatók nem ismerhetnek. Itt is hozzáadható a funkciók listája vagy a háttér alszakasz. Ha vannak alternatívák a projekthez, ez egy jó hely a differenciáló tényezők felsorolására.
jelvények
néhány READMEs-en kis képeket láthat, amelyek metaadatokat közvetítenek, például azt, hogy az összes teszt elhalad-e a projekthez. Használhatja pajzsok hozzá néhány a README. Számos szolgáltatásnak van útmutatása a jelvény hozzáadásához.,
vizuális
attól függően, hogy mit csinálsz, jó ötlet lehet képernyőképeket vagy akár videót is felvenni (gyakran látni fogja a GIF-eket, nem pedig a tényleges videókat). Eszközök, mint a ttygif segíthet, de nézd meg Asciinema egy kifinomultabb módszer.
telepítés
egy adott ökoszisztémán belül előfordulhat, hogy a dolgok telepítésének közös módja van, például fonal, NuGet vagy Homebrew. Azonban, fontolja meg annak lehetőségét, hogy bárki is olvassa el a README egy kezdő, és szeretne több útmutatást., A konkrét lépések felsorolása segít eltávolítani a kétértelműséget, így az emberek a lehető leggyorsabban használhatják a projektet. Ha csak egy adott környezetben fut, mint például egy adott programozási nyelv verziója vagy operációs rendszere, vagy vannak olyan függőségek, amelyeket manuálisan kell telepíteni, akkor adjon hozzá egy követelmény alfejezetet is.
Usage
használjon példákat liberálisan, és mutassa meg a várt kimenetet, ha tud. Hasznos, hogy inline a legkisebb példa a használat, hogy bizonyítani tudja, miközben linkeket kifinomultabb példákat, ha túl hosszú ahhoz, hogy ésszerűen tartalmazza a README.,
támogatás
mondja el az embereknek, hogy hol tudnak segítséget kérni. Ez lehet bármilyen kombinációja egy probléma tracker, egy chat-szobában, egy e-mail címet, stb ..
Útiterv
Ha a jövőben ötletei vannak a kiadásokra, akkor jó ötlet felsorolni őket a README-ben.
hozzájárulás
jelezze, hogy nyitott-e a hozzájárulásokra, és milyen követelményei vannak azok elfogadására.
azok számára, akik szeretnék, hogy módosítsa a projekt, ez hasznos, hogy néhány dokumentációt, hogyan kell elkezdeni., Talán van egy szkript, amelyet futtatniuk kell, vagy néhány környezeti változót, amelyeket be kell állítaniuk. Tegye egyértelművé ezeket a lépéseket. Ezek az utasítások hasznosak lehetnek a jövőbeli éned számára is.
a parancsokat is dokumentálhatja a kód beillesztéséhez vagy a tesztek futtatásához. Ezek a lépések segítenek a magas kódminőség biztosításában, valamint csökkentik annak valószínűségét, hogy a változások véletlenül megtörnek valamit. A tesztek futtatására vonatkozó utasítások különösen akkor hasznosak, ha külső beállításra van szükség, például egy Szelénkiszolgáló indítása a böngészőben történő teszteléshez.,
szerzők és elismerések
mutassa meg elismerését azoknak, akik hozzájárultak a projekthez.
License
nyílt forráskódú projektekhez mondja el, hogyan engedélyezett.
projekt állapota
Ha elfogyott az energiája vagy ideje a projektnek, tegyen egy megjegyzést a README tetejére, mondván, hogy a fejlesztés lelassult vagy teljesen leállt. Valaki dönthet úgy, hogy Villa a projekt vagy önkéntes, hogy lépjen be, mint a karbantartó vagy tulajdonos, amely lehetővé teszi a projekt, hogy folyamatosan megy. Azt is, hogy egy explicit kérelmet karbantartók.