Dokumentation af projektet

Den skal indeholde alle de aspekter, som udvikleren har brug for at vide, og som ikke kan fås direkte fra producenten. Kode. De indeholder bl.a., hvad man skal og ikke skal gøre i forbindelse med udvikling, fulde implementeringsinstruktioner, beskrivelser af ekstern integration osv. Dette indlæg vil guide dig gennem oprettelsen af en stærk, smuk og læselig README-fil til din projekt.

En god introduktion til velforberedt projektdokumentation kan findes på github guides: https://guides.github.com/features/wikis/. Her står der, at "README bør kun indeholde de nødvendige oplysninger for, at udviklere kan komme i gang med at bruge og bidrage til projektet".

Med dette i tankerne introducerer vi en liste over komponenter og bedste praksis, som vi følger hos Codest for at skabe projektdokumentation.

Hurtig introduktion

- Projektets titel: Dette er et must-have for enhver README.

- Status-badges: Hvis du bruger eksterne kodekvalitetsmålinger, automatiserede test eller andre værktøjer, er begyndelsen af dokumentet et godt sted at vise andre, om de fungerer.

- Beskrivelse: medtag et par sætninger om projektet for hurtigt at beskrive hovedformålet, og hvad det gør.

Indholdsfortegnelse

En indholdsfortegnelse kan være nyttig for lange dokumentationsfiler, men hvis din README er ganske kortfattet, er det ikke nødvendigt.

Generel information

- Om sektionen: dette bør være en mere detaljeret beskrivelse af projektet - det kan indeholde oplysninger om brugere, deres roller, nogle mere forvirrende tilfælde og skærmbilleder osv.

- Mockups: et sted til links til UI/UX mockup-ressourcer, hvis der er nogen.

• Andre oplysninger som Adgang til servere eller Integration med eksterne API'er: eksempler omfatter en url-adresse til staging-instansen, delte ikke-følsomme (!) adgangsoplysninger, links til dokumentation, nogle instruktioner osv.

Installation

- Kravene: Forudsætninger, der skal opfyldes, før du starter en programopsætning, f.eks. installation af eksterne værktøjer.

- Opsætning: en trin-for-trin-vejledning, der skal følges for at få projektet op at køre.

- Indstillinger: beskriver, hvor de lokale indstillinger er gemt, og giver instruktioner om, hvordan du modtager dine egne indstillinger.

- Lokal konfiguration: Hvis der er nogle tilfælde af lokal opsætning, er dette et godt sted at få en forklaring.

Udvikling

Dette afsnit er et ideelt sted til instruktioner om f.eks. udvikling af funktioner, fejlrettelser, hotfixes, fælles funktioner, testning, stilvejledninger, kodeorganisering, andre udviklingsværktøjer, der bruges i projektet (f.eks. guards eller dockers) osv. Glem ikke at nævne alle de regler, som alle hold medlem bør vide.

Udrulning

Giv klare trinvise instruktioner for hvert miljø og alt, hvad der er "godt at vide", mens du foretager udrulningen.

Andre ideer til separate sektioner

- API-dokumentation

- Changelog

- Eksterne ressourcer: et sted for alle slags links, der kan være nyttige.

- Applikationsstakken: en liste over den applikationsstack, vi bruger i projektet - kan indeholde en kort beskrivelse og navnet på udbyderen.

Team

Det kan diskuteres, om det er nødvendigt at vise aktuelle projektteammedlemmer (github giver som standard den fulde liste over bidragydere), men det er altid rart, hvis man kan se sit navn som en af forfatterne til et projekt. Hvis du gør det, så hold det så opdateret som muligt.

Et par sidste ord

Husk: Hvert projekt er unikt, og det er dets dokumentation også. Der er ikke én god løsning til at skrive en README. Bare følg de generelle tips, og det vigtigste er altid at huske på refaktorering, som også har forbindelse til README. Det er altid en god idé at se på dokumentet som helhed og genoverveje det, hvis noget skal vises på en anden måde.

En ting mere: "Instruktioner" er vigtige, så skriv dem meget. Tak skal I have!

Læs mere om det:

• Åben-lukket-princippet. Får jeg nogensinde brug for det?
• Hvordan skriver man en god kvalitetskode?
• Vuelendar. Et nyt Codest-projekt baseret på Vue.js