Prosjektdokumentasjon

Den bør inneholde alle aspekter som utvikleren trenger å vite, og som ikke kan mottas direkte fra kode. Disse inneholder blant annet hva du bør og ikke bør gjøre under utviklingen, fullstendige distribusjonsinstruksjoner, beskrivelser av ekstern integrasjon og så videre. Dette innlegget vil veilede deg gjennom hvordan du lager en kraftig, vakker og leselig README-fil for din prosjekt.

En fin introduksjon til godt forberedt prosjektdokumentasjon finner du på github guides: https://guides.github.com/features/wikis/. Her står det at "README skal bare inneholde den informasjonen som er nødvendig for at utviklere skal komme i gang med å bruke og bidra til prosjektet".

Med dette i bakhodet vil vi presentere en liste over komponenter og beste praksis vi i Codest følger når vi lager prosjektdokumentasjon.

Rask introduksjon

- Prosjektets tittel: dette er et must for enhver README.

- Statusmerker: Hvis du bruker eksterne kodekvalitetsmålinger, automatiserte tester eller andre verktøy, er begynnelsen av dokumentet et godt sted å vise andre om de fungerer.

- Beskrivelse: ta med noen få setninger om prosjektet for raskt å beskrive hovedformålet og hva det gjør.

Innholdsfortegnelse

En innholdsfortegnelse kan være nyttig for lange dokumentasjonsfiler, men hvis README-filen er ganske kortfattet, er det ikke nødvendig.

Generell informasjon

- Om seksjonen: dette bør være en mer detaljert beskrivelse av prosjektet - den kan inneholde informasjon om brukere, deres roller, noen mer forvirrende tilfeller, skjermbilder osv.

- Mockups: et sted for lenker til UI/UX mockup-ressurser, hvis det finnes noen.

• Annen informasjon som Tilgang til servere eller Integrering med eksterne API-er: eksempler inkluderer en url-adresse til en staging-instans, delt, ikke-sensitiv (!) tilgangsinformasjon, lenker til dokumentasjon, noen instruksjoner osv.

Installasjon

- Krav: Forutsetninger som må oppfylles før du starter en applikasjonsinstallasjon, f.eks. installasjon av eksterne verktøy.

- Oppsett: en trinnvis instruksjon som skal følges for å få prosjektet i gang.

- Innstillinger: beskriver hvor de lokale innstillingene er lagret, og gir instruksjoner om hvordan du mottar dine egne innstillinger.

- Lokal konfigurasjon: Hvis det finnes noen tilfeller for lokalt oppsett, er dette et godt sted for en forklaring.

Utvikling

Denne delen er et ideelt sted for instruksjoner om for eksempel utvikling av funksjoner, feilrettinger, hotfixes, fellesfunksjoner, testing, stilguider, kodeorganisering, andre utviklingsverktøy som brukes i prosjektet (f.eks. guards eller dockers), og så videre. Ikke glem å nevne alle reglene som alle team medlem bør vite.

Utplassering

Gi tydelige trinnvise instruksjoner for hvert miljø og alt som er "godt å vite" når du skal gjøre utplasseringen.

Andre ideer til separate seksjoner

- API-dokumentasjon

- Endringslogg

- Eksterne ressurser: et sted for alle slags lenker som kan være til hjelp.

- Applikasjonsstakken: en liste over applikasjonsstakken som vi bruker i prosjektet - kan inneholde en kort beskrivelse og navnet på leverandøren.

Team

Det kan diskuteres om det er nødvendig å vise aktuelle medlemmer av prosjektteamet (github gir en fullstendig liste over bidragsytere som standard), men det er alltid hyggelig hvis du ser navnet ditt som en av forfatterne av et prosjekt. Hvis du gjør dette, bør du holde det så oppdatert som mulig.

Noen siste ord

Husk at hvert prosjekt er unikt, og det er dokumentasjonen også. Det finnes ikke én god løsning for å skrive en README. Bare følg de generelle tipsene, og det viktigste er å alltid huske på refaktorering, som også er knyttet til README. Det er alltid en god idé å se på dokumentet som en helhet og tenke nytt hvis noe må vises på en annen måte.

En ting til: "instruksjoner" er nøkkelen, så skriv dem mye. Takk skal dere ha!

Les mer om dette:

• Åpen-lukket-prinsippet. Må jeg noen gang bruke det?
• Hvordan skriver man en god kode av høy kvalitet?
• Vuelkalender. Et nytt Codest-prosjekt basert på Vue.js