Tee README
Ehdotuksia hyvä README
Jokainen projekti on erilainen, joten mieti, mitkä näistä kohdista hakea omasi. Mallissa käytetyt osiot ovat ehdotuksia useimpiin avoimen lähdekoodin projekteihin. Muista myös, että vaikka README voi olla liian pitkä ja yksityiskohtainen, liian pitkä on parempi kuin liian lyhyt. Jos luulet, että README on liian pitkä, harkitse hyödyntämällä toinen muoto asiakirjat, pikemminkin kuin leikkaamalla tietoja.
Nimi
Valitse itsestäänselvä nimi projektin.,
kuvaus
kerro ihmisille, mitä projektisi voi erityisesti tehdä. Anna asiayhteys ja lisää linkki kaikkiin viitevieraisiin, joita ei ehkä tunneta. Tähän voi lisätä myös listan ominaisuuksista tai Taustalohkon. Jos hankkeelle on vaihtoehtoja, tämä on hyvä paikka luetella eriäviä tekijöitä.
Merkit
joissakin READMEs, voit nähdä pieniä kuvia, jotka välittää metatietoja, kuten onko tai ei kaikki testit ovat kulkevan projektin. Voit käyttää suojia lisätä joitakin README. Monissa palveluissa on myös ohjeet virkamerkin lisäämiseen.,
Grafiikka
Riippuen siitä, mitä olet tekemässä, se voi olla hyvä idea sisällyttää kuvakaappauksia tai jopa video (you”ll usein nähdä Gif pikemminkin kuin todellinen videot). Työkalut kuten ttygif voi auttaa, mutta tutustu Asciinema kehittyneempi menetelmä.
Asennus
tietyn ekosysteemin, ei voi olla yleinen tapa asentaa asioita, kuten käyttämällä Lanka, NuGet, tai Homebrew. Harkitse kuitenkin mahdollisuutta, että lukijasi on noviisi ja haluaisi lisää opastusta., Listaamalla tiettyjä vaiheita auttaa poistamaan epäselvyyttä ja saa ihmiset käyttämään projektia mahdollisimman nopeasti. Jos se toimii vain tietyssä yhteydessä, kuten tietyn ohjelmointikielen versio tai käyttöjärjestelmän tai on riippuvuuksia, jotka on asennettu manuaalisesti, myös lisää Vaatimuksia momentissa.
Käyttö
Käytä runsaasti esimerkkejä, ja näyttää odotettu tuotos, jos voit. Se”s hyvä olla inline pienin esimerkki käyttöä, että voit osoittaa, samalla linkkejä kehittyneempiä esimerkkejä, jos ne ovat liian pitkiä, jotta voidaan kohtuudella sisällä README.,
tuki
kerro ihmisille, mistä he voivat hakea apua. Se voi olla mikä tahansa yhdistelmä ongelma tracker, chat, sähköpostiosoite, jne.
Tiekartan
Jos sinulla on ideoita tiedotteet tulevaisuudessa, se on hyvä idea luetella ne README.
Edistää
– Tilassa, jos olet avoin maksuja ja mitä vaatimuksia hyväksyä ne.
ihmisille, jotka haluavat tehdä muutoksia projektiisi, on hyödyllistä saada joitakin asiakirjoja siitä, miten pääset alkuun., Ehkä on olemassa skripti, että heidän pitäisi ajaa tai joitakin ympäristömuuttujia, jotka he tarvitsevat asettaa. Tee nämä vaiheet selviksi. Näistä ohjeista voisi olla hyötyä myös tulevalle itselle.
voit myös dokumentoida komentoja koodin nukkaamiseen tai testien suorittamiseen. Nämä vaiheet auttavat varmistamaan koodin korkea laatu ja vähentää todennäköisyyttä, että muutokset vahingossa rikkoa jotain. Ottaa ohjeet testejä on erityisen hyödyllistä, jos se vaatii ulkoisen setup, kuten alkaa Seleeni-palvelimen testaus-selaimessa.,
tekijät ja tunnustus
osoittavat arvostuksesi hankkeeseen osallistuneille.
lisenssi
avoimen lähdekoodin projekteille, kerro miten se on lisensoitu.
Projekti-tila
Jos sinulla on ajaa ulos energiaa tai aikaa projektin, laittaa huomautus yläreunassa README sanomalla, että kehitys on hidastunut tai pysähtynyt kokonaan. Joku voi valita haarukka projektin tai vapaaehtoinen vaihe, kuten ylläpitäjä tai omistaja, jolloin projekti jatkaa. Voit myös tehdä nimenomaisen pyynnön ylläpitäjille.