Hvordan skrive dokumentasjon for programvare: 8 trinn (med bilder)

Innhold

Trinn
- Metode 1 av 2: Skrive programvaredokumentasjon for tekniske brukere
- Metode 2 av 2: Skrive programvaredokumentasjon for sluttbrukere
Tips
Nødvendigheter

God programvaredokumentasjon, enten det er et spesifikasjonsdokument for programmerere og testere, et teknisk dokument for kolleger, eller programvarehåndbøker og hjelpefiler for sluttbrukere, hjelper personen som må jobbe med programvaren til å forstå alle dens funksjoner og funksjoner. God programvaredokumentasjon er spesifikk, kortfattet og relevant, og gir all viktig informasjon til personen som bruker programvaren. Nedenfor finner du instruksjoner om hvordan du skriver programvaredokumentasjon for tekniske brukere og sluttbrukere.

Trinn

Metode 1 av 2: Skrive programvaredokumentasjon for tekniske brukere

Bilde med tittelen Write Software Documentation Step 1

1. Bestem hvilken informasjon som skal inkluderes. Programvarespesifikasjoner fungerer som guider for brukergrensesnittdesignere, programmerere som skriver koden og testere som bekrefter at programvaren fungerer etter hensikten. Den eksakte informasjonen avhenger av programmet det gjelder, men kan inkludere noe av følgende:

De viktigste filene i applikasjonen. Disse kan være filer opprettet av utviklingsteamet, databaser som er åpnet under programdrift, og tredjepartsverktøy.
Funksjoner og underrutiner. Dette inkluderer en forklaring på hva hver funksjon eller subrutine gjør, inkludert alle inngangs- og utgangsverdier.
Programvariabler og konstanter, og hvordan de brukes i applikasjonen.
Den generelle programstrukturen. For en diskbasert applikasjon kan dette være en beskrivelse av programmets individuelle moduler og biblioteker, mens for en nettapplikasjon kan det beskrive hvilke sider som bruker hvilke filer.

Bilde med tittelen Write Software Documentation Step 2

2. Bestem hvor mye av dokumentasjonen som skal inkluderes i programkoden og hvor mye som skal holdes adskilt. Jo mer teknisk dokumentasjon som allerede er utviklet innenfor kildekoden til programmet, desto lettere blir det å oppdatere og vedlikeholde den sammen med koden, samt å dokumentere ulike versjoner av den originale applikasjonen. Dokumentasjon i kildekoden bør som et minimum forklare formålet med funksjoner, subrutiner, variabler og konstanter.

Hvis kildekoden er spesielt lang, kan den dokumenteres i form av en hjelpefil, som kan indekseres og søkes med nøkkelord. Dette er en spesiell fordel for applikasjoner der programlogikken er fragmentert over mange sider og inneholder en rekke tilleggsfiler, for eksempel med visse nettapplikasjoner.

Noen programmeringsspråk, som Java og .NET Framework (Visual Basic.NET, C#), har sine egne standarder for å dokumentere koden. Følg i disse tilfellene standardene om hvor mye av dokumentasjonen som skal inkluderes i kildekoden.

Bilde med tittelen Write Software Documentation Step 3

3. Velg riktig dokumentasjonsverktøy. Til en viss grad bestemmes dette av språket som koden er skrevet på (som C++, C#, Visual Basic, Java eller PHP), ettersom det finnes spesifikke verktøy for disse og andre språk. I andre tilfeller avgjør typen dokumentasjon som kreves, hvilket verktøy som skal brukes.

Tekstbehandlingsprogrammer for Microsoft Word er tilstrekkelig for å lage separate tekstfiler for dokumentasjon, så lenge dokumentasjonen er ganske kort og enkel. For lange, komplekse tekstfiler foretrekker mange tekniske forfattere et dokumentasjonsverktøy som Adobe FrameMaker.

Hjelpefiler for å dokumentere kildekoden kan produseres med et hvilket som helst hjelpeforfatterverktøy, for eksempel RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare eller HelpLogix.

Metode 2 av 2: Skrive programvaredokumentasjon for sluttbrukere

Bilde med tittelen Write Software Documentation Step 4

1. Bestem forretningsgrunnene for dokumentasjonen din. Selv om den funksjonelle grunnen til å dokumentere programvare er å hjelpe brukere med å forstå hvordan de skal bruke applikasjonen, er det andre grunner som å hjelpe til med å markedsføre programvaren, forbedre bedriftens image og, viktigst av alt, redusere tekniske støttekostnader. I noen tilfeller er dokumentasjonen nødvendig for å overholde visse forskrifter eller andre lovkrav.

Imidlertid bør på ingen måte programvaredokumentasjon være en erstatning for dårlig grensesnittdesign. Hvis en applikasjon krever sider med dokumentasjon som veiledning, er det bedre å endre skjermdesignet til noe mer intuitivt.

Bilde med tittelen Write Software Documentation Step 5

2. Forstå publikummet du skriver dokumentasjonen for. I de fleste tilfeller har programvarebrukere lite kunnskap om datamaskiner utover oppgavene de kan utføre med applikasjonene de bruker. Det er flere måter å finne ut hva de trenger og hvordan dokumentasjonen din kan møte dem.

Se på funksjonene dine potensielle brukere har. En systemadministrator er sannsynligvis en ekspert på en rekke programvareapplikasjoner, mens en dataregistreringsassistent sannsynligvis bare kjenner applikasjonen han eller hun bruker for å legge inn data.

Se på brukerne selv. Mens stillingstitler vanligvis indikerer hva folk gjør, kan det være betydelige forskjeller i hvordan visse stillinger fylles i en organisasjon. Ved å intervjue potensielle brukere kan du få en ide om ditt inntrykk av det deres posisjon indikerer er riktig eller ikke.

Se eksisterende dokumentasjon. Dokumentasjon for tidligere versjoner av programvaren (samt funksjonelle spesifikasjoner) gir en indikasjon på hva brukeren trenger å vite for å bruke programmet. Men husk at sluttbrukere egentlig ikke er interessert i hvordan programmet fungerer, men i hva det kan gjøre for dem.

Bestem oppgavene som må gjøres for å fullføre en oppgave, og hvilke oppgaver som må gjøres før disse oppgavene kan utføres.

Bilde med tittelen Write Software Documentation Step 6

3. Bestem riktig format for dokumentasjonen. Programvaredokumentasjon kan struktureres i 1 av 2 formater: manualen og brukermanualen. Noen ganger er en kombinasjon av begge formatene den beste tilnærmingen.

En referanseguide er viet til å forklare de individuelle funksjonene til et program (knapper, faner, felt og dialogboks) og hvordan de fungerer. Mange hjelpefiler er skrevet i dette formatet, spesielt kontekstsensitiv hjelp som viser et relevant emne når en bruker klikker på Hjelp-knappen på en bestemt skjerm.

En brukerveiledning forklarer hvordan du bruker programvaren til å utføre en bestemt oppgave. Brukerhåndbøker er ofte formatert som trykte veiledninger eller PDF-er, selv om noen hjelpefiler inneholder emner om hvordan du utfører visse oppgaver. (Disse hjelpeemnene er vanligvis ikke kontekstavhengige, selv om de kan være knyttet til emner som er det.) Brukerveiledninger kommer ofte i form av veiledninger, med oversikt over oppgavene som skal utføres i innledningen og instruksjoner gitt i nummererte trinn.

Bilde med tittelen Write Software Documentation Step 7

4. Bestem hvilken form dokumentasjonen skal ha. Programvaredokumentasjon kan ha mange former: manualer, PDF-dokumenter, hjelpefiler eller elektronisk hjelp. Hvert skjema er utformet for å vise brukeren bruken av hver av funksjonene i programmet, enten det er i form av en gjennomgang eller veiledning; når det gjelder hjelpefiler og nettbasert hjelp, kan dette være tekst så vel som demonstrasjonsvideoer samt bilder.

Hjelpefiler og elektronisk hjelp bør være indeksert og søkbare med nøkkelord, slik at brukerne raskt kan finne informasjonen de trenger. Mens hjelpefilbyggere kan generere indekser automatisk, er det ofte bedre å lage indeksen manuelt ved å bruke termer som brukere vanligvis søker etter.

Bilde med tittelen Write Software Documentation Step 8

5. Velg et passende dokumentasjonsverktøy. Trykte eller PDF-manualer kan skrives ved hjelp av et tekstbehandlingsprogram som Word, eller et avansert tekstredigeringsprogram som FrameMaker, avhengig av lengden og kompleksiteten. Hjelpefiler kan skrives med et spesielt forfatterverktøy som RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix eller HelpServer.

Tips

Teksten bør organiseres slik at den er lett å lese, med bilder så nærme som mulig teksten den refererer til. Del dokumentasjonen logisk inn i avsnitt, avsnitt og emner. Hvert avsnitt eller emne må forklare et enkelt problem, enten det er en enkelt programfunksjon eller en oppgave. Relaterte problemer kan forklares, der det er hensiktsmessig, ved å bruke "Se også"-lister eller hyperkoblinger som nevnt ovenfor.
Ethvert av dokumentasjonsverktøyene som er oppført ovenfor kan suppleres med et skjermbildeprogram, for eksempel Snagit, hvis dokumentasjonen krever noen skjermbilder. Som med annen dokumentasjon, bør skjermbilder inkluderes for å forklare hvordan programvaren fungerer, ikke for å forvirre brukeren.
Tone er veldig viktig, spesielt når du skriver programvaredokumentasjon for sluttbrukere. Adresser brukere i den andre personen ("deg") i stedet for den tredje personen ("brukeren").