Gjøre en README –
Forslag til en god README
Hvert prosjekt er forskjellig, så bør du vurdere hvilke av disse punktene gjelder for deg. Delene som brukes i malen er forslag for de fleste open source prosjekter. Husk også på at mens en README kan være for lang og detaljert, for lenge er bedre enn for kort. Hvis du tror at din README er for lang, kan du vurdere å benytte en annen form for dokumentasjon heller enn å kutte ut informasjon.
Navn
Velg en selvforklarende navn for ditt prosjekt.,
Beskrivelse
La folk få vite hva ditt prosjekt kan gjøre spesielt. Gi kontekst, og legg til en link til noen referanse besøkende kan bli kjent med. En liste over Funksjoner eller en Bakgrunn ledd kan også legges her. Hvis det finnes alternativer til prosjektet, dette er et godt sted å liste differensierende faktorer.
Merkene
På noen READMEs, kan du se små bilder som formidler metadata, for eksempel hvorvidt alle testene er bestått for prosjektet. Du kan bruke Skjold for å legge noen til README. Mange tjenester har også instruksjoner for hvordan du legger til et merke.,
Visuelle
Avhengig av hva du gjør, kan det være en god idé å ta med skjermbilder eller en video du vil ofte se Gif-filer i stedet for faktiske videoer). Verktøy som ttygif kan hjelpe, men sjekk ut Asciinema for en mer sofistikert metode.
Installasjon
Innenfor et avgrenset økosystem, det kan være en vanlig måte å installere ting, som for eksempel bruk av Garn, NuGet, eller Homebrew. Imidlertid, bør du vurdere muligheten for at den som er å lese README er en nybegynner og ønsker mer veiledning., Oppføring fremgangsmåten bidrar til å fjerne tvetydighet og får folk til å bruke prosjektet så raskt som mulig. Hvis det bare går i en bestemt kontekst som et bestemt programmeringsspråk versjon eller operativsystem eller har avhengigheter som må installeres manuelt, kan du også legge til et Krav ledd.
– Bruk
Bruk eksempler i rikt monn, og viser forventet output hvis du kan. Det er nyttig å ha inline den minste eksempel på bruk at du kan vise til, samtidig som det gir koblinger til mer sofistikerte eksempler hvis de er for lange til rimelig inkluderer i README.,
Support
Fortell folk hvor de kan gå til for å få hjelp. Det kan være hvilken som helst kombinasjon av et problem tracker, et chat-rom, en e-postadresse, etc.
Veikart
Hvis du har ideer til utgivelser i fremtiden, er det en god idé å liste dem i README.
Bidrar
– modus hvis du er åpen for bidrag og hva dine behov er for å akseptere dem.
For folk som ønsker å gjøre endringer i ditt prosjekt, det er nyttig å ha noen dokumentasjon på hvordan å komme i gang., Kanskje er det et skript som de skal løpe eller noen miljøvariabler som de trenger for å stille inn. Gjør du disse trinnene eksplisitt. Disse instruksjonene kan også være nyttig for din fremtidige selv.
Du kan også dokumentere kommandoer til lo-koden eller kjører tester. Disse trinnene bidra til å sikre høy kvalitet kode og redusere sannsynligheten for at endringer utilsiktet ødelegge noe. Etter å ha instruksjoner for å kjøre testene er spesielt nyttig hvis det krever ekstern oppsett, for eksempel starte en Selen server for testing i en nettleser.,
Forfattere og anerkjennelse
Vis din takknemlighet til de som har bidratt til prosjektet.
Lisens
For åpen kildekode-prosjekter, sier hvordan det er lisensiert.
Prosjekt status
Hvis du kjører ut av energi eller tid for prosjektet ditt, sette en lapp på toppen av det VIKTIG å si at utviklingen har bremset eller stoppet helt. Noen kan velge å fork ditt prosjekt eller frivillig å gå inn som vedlikeholder eller eier, slik at prosjektet å holde det gående. Du kan også gjøre en eksplisitt avtale for utviklere.