Hur förbereder jag dokumentation för ett projekt?

Skriv titeln för ditt projekt. När du skriver en README för ditt projekt är det första du bör inkludera projektets titel. Tillsammans med titeln bör du också inkludera det senaste versionsnumret och det datum då det senast uppdaterades.

Skriv en beskrivning av ditt projekt. Nästa sak du behöver inkludera i din README är en kort beskrivning av ditt projekt. Förklara vad projektet gör, varför det finns och vilka problem det löser. Du kan också inkludera alla specialfunktioner, skärmdumpar, kodstil, teknik eller ramverk som används eller något annat som kan vara till hjälp för användare och utvecklare.

Förklara eventuella krav som ditt projekt har. Om ditt projekt behöver några speciella krav för att kunna fungera ordentligt, se till att lista dessa krav och instruktioner, eller en länk till instruktioner om hur du installerar dem.

Inkludera ett exempel på koden. Ge ett tydligt och koncist exempel på vad ditt projekt används till. Koden ska vara lätt för utvecklare att räkna ut, och API: et ska vara tydligt synligt.

Ge installationsinstruktioner. Förklara för användarna hur du startar din programvara i steg-för-steg-format. Dina instruktioner ska vara så tydliga som möjligt. Antag att dina användare inte har någon kunskap om programvaruutveckling eller systemadministration.

Förklara hur du använder programvaran. Berätta för folk hur du får ut det mesta av din programvara. Ge steg-för-steg-instruktioner om hur du använder din programvara samt olika konfigurationsalternativ och hur du ställer in dem.

Berätta för användare hur man får teknisk hjälp. Ger länkar till alla e- postlistor, IRC-kanaler eller communityforum som användarna kan vända sig till för teknisk hjälp. Låt också mer erfarna användare veta var de ska skicka buggar och idéer för att göra projektet bättre.

• Om du upptäcker att du får många samma frågor från olika användare kanske du vill inkludera en FAQ (vanliga frågor) som en del av din projektdokumentation.

Förklara hur man kan bidra. Om du arbetar med ett open source-projekt, låt dina användare veta hur de kan bidra till ditt projekt. Förklara eventuella standarder och ge några riktlinjer till potentiella bidragsgivare.

Lista poängen. Ge alltid kredit där kredit förfaller. Var noga med att lista namnen på alla bidragsgivare samt länkar till eventuella tredjepartsbibliotek eller program som du har använt. Inkludera länkar till all inspiration du kan ha haft när du byggde ditt projekt.

Ange din kontaktinformation. Människor kanske vill kontakta dig av olika orsaker. Var noga med att ange en giltig e-postadress som människor kan använda för att kontakta dig.

• Vissa länder kan kräva ytterligare information, t.ex. en postadress eller företagsnamn enligt lag.

Ge licensinformation. Det är viktigt för användare att veta hur ditt projekt licensieras. Det finns många standardlicenser på nätet som du kan använda. Förklara vilken licens ditt projekt använder, samt licenserna för eventuella tredjepartsbibliotek eller program du kan använda.

• Du behöver inte förklara hela licensen i dina dokumentationer. Låt bara användarna veta vilken licens ditt projekt använder och ge en länk till fullständig licensinformation.