God programvaredokumentasjon, enten det er spesifikasjonsdokumentasjon for programmerere og testere, tekniske dokumenter for interne brukere, eller manualer og hjelpefiler for sluttbrukere, vil hjelpe brukerne å forstå funksjonene og funksjonene til programvaren. God dokumentasjon er dokumentasjon som er spesifikk, tydelig og relevant, med all informasjonen brukeren trenger. Denne artikkelen vil guide deg til å skrive programvaredokumentasjon for tekniske brukere og sluttbrukere.
Steg
Metode 1 av 2: Skrive programvaredokumentasjon for tekniske brukere
Trinn 1. Vet hvilken informasjon du skal inkludere
Spesifikasjonsdokumentet brukes som en referansehåndbok for grensesnittdesignere, programmerere som skriver kode og testere som bekrefter programvarens ytelse. Informasjonen som må inkluderes vil avhenge av programmet som opprettes, men kan inneholde følgende:
- Viktige filer i programmet, for eksempel filer opprettet av utviklingsteamet, databaser som du får tilgang til mens programmet kjører, og tredjepartsapplikasjoner.
- Funksjoner og underrutiner, inkludert en forklaring på bruken av funksjonen/subrutinen, inngangs- og utgangsverdier.
- Programvariabler og konstanter, og hvordan de brukes.
- Overordnet programstruktur. For stasjonsbaserte programmer må du kanskje beskrive hver modul og bibliotek. Eller hvis du skriver en håndbok for et nettbasert program, må du kanskje forklare hvilke filer hver side bruker.
Trinn 2. Bestem hvilket dokumentasjonsnivå som skal være tilstede og kan skilles fra programkoden
Jo mer teknisk dokumentasjon som er inkludert i programkoden, jo lettere blir det å oppdatere og vedlikeholde den, samt å forklare de forskjellige versjonene av programmet. Dokumentasjonen i programkoden bør minst inneholde bruk av funksjoner, underrutiner, variabler og konstanter.
- Hvis kildekoden din er lang, kan du skrive dokumentasjon i en hjelpefil, som deretter kan indekseres eller søkes med bestemte søkeord. Separate dokumentasjonsfiler er nyttige hvis programlogikken er delt over flere sider og inkluderer støttefiler, for eksempel et webprogram.
- Noen programmeringsspråk (for eksempel Java, Visual Basic. NET eller C#) har sine egne kodedokumentasjonsstandarder. I slike tilfeller må du følge standarddokumentasjonen som må være inkludert i kildekoden.
Trinn 3. Velg det riktige dokumentasjonsverktøyet
I noen tilfeller bestemmes dokumentasjonsverktøyet av programmeringsspråket som brukes. Språkene C ++, C#, Visual Basic, Java, PHP og andre har sine egne dokumentasjonsverktøy. Hvis ikke, vil imidlertid verktøyene som brukes, avhenge av nødvendig dokumentasjon.
- En tekstbehandler som Microsoft Word er egnet for å lage dokumenttekstfiler, så lenge dokumentasjonen er kortfattet og enkel. For å lage lang dokumentasjon med kompleks tekst, velger de fleste tekniske forfattere et spesialisert dokumentasjonsverktøy, for eksempel Adobe FrameMaker.
- Hjelpefiler for dokumentasjon av kildekoden kan opprettes med et støttefilgeneratorprogram, for eksempel RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare eller HelpLogix.
Metode 2 av 2: Skrive programvaredokumentasjon for sluttbrukere
Trinn 1. Kjenn de forretningsmessige årsakene som ligger til grunn for utarbeidelsen av håndboken
Selv om hovedårsaken til programvaredokumentasjon er å hjelpe brukerne til å forstå hvordan de bruker programmet, er det flere andre grunner som kan ligge til grunn for å lage dokumentasjon, for eksempel å hjelpe markedsavdelingen med å selge applikasjonen, forbedre selskapets image og redusere teknisk støtte kostnader. I noen tilfeller kreves dokumentasjon for å overholde forskrifter eller andre lovkrav.
Imidlertid er dokumentasjon ikke en god erstatning for et grensesnitt. Hvis en applikasjon krever mye dokumentasjon for å fungere, bør den være utformet for å være mer intuitiv
Trinn 2. Kjenn målgruppen for dokumentasjonen
Generelt har programvarebrukere begrenset datakunnskap utover applikasjonene de bruker. Det er flere måter å dekke dokumentasjonsbehovet på:
- Vær oppmerksom på tittelen på programvarebrukeren. For eksempel forstår systemadministratoren generelt forskjellige dataprogrammer, mens sekretæren bare kjenner programmene han bruker for å legge inn data.
- Vær oppmerksom på programvarebrukere. Selv om stillingene deres generelt er kompatible med oppgavene som utføres, kan disse stillingene ha forskjellige arbeidsmengder, avhengig av virksomhetsstedet. Ved å intervjue potensielle brukere kan du finne ut om vurderingen av jobbtittelen din er riktig.
- Vær oppmerksom på eksisterende dokumentasjon. Programvarefunksjonalitetsdokumentasjon og spesifikasjoner kan vise hva brukerne trenger å vite for å bruke dem. Vær imidlertid oppmerksom på at brukerne ikke er interessert i å kjenne til programmets "indre".
- Vet hva som skal til for å fullføre en oppgave, og hva som skal til før du kan fullføre den.
Trinn 3. Bestem passende format for dokumentasjonen
Programvaredokumentasjon kan ordnes i 1 eller 2 formater, nemlig oppslagsbøker og manualer. Noen ganger er det en god løsning å kombinere de to formatene.
- Referanseformater brukes til å beskrive alle programvarefunksjoner, for eksempel knapper, faner, felt og dialogbokser, og hvordan de fungerer. Noen hjelpefiler er skrevet i dette formatet, spesielt de som er kontekstsensitive. Når brukeren klikker på Hjelp i en bestemt skjerm, vil brukeren motta det aktuelle emnet.
- Det manuelle formatet brukes til å forklare hvordan du gjør noe med programvaren. Manualer er vanligvis i trykt eller PDF -format, selv om noen hjelpesider også inneholder instruksjoner om hvordan du gjør visse ting. (Vanligvis er manuelle formater ikke kontekstsensitive, men kan være koblet fra kontekstsensitive emner). Håndbøker er vanligvis i form av en guide, med en oppsummering av oppgavene som skal utføres i en beskrivelse og en guide som er formatert i trinn.
Trinn 4. Bestem deg for typen dokumentasjon
Programvaredokumentasjon for brukere kan være pakket i ett eller flere av følgende formater: trykte håndbøker, PDF -filer, hjelpefiler eller elektronisk hjelp. Hver type dokumentasjon er designet for å vise deg hvordan du bruker programvarens funksjoner, enten det er en guide eller en opplæring. Online dokumentasjon og hjelpesider kan også inneholde demonstrasjonsvideoer, tekst og statiske bilder.
Online hjelp- og støttefiler bør indekseres og søkes ved hjelp av søkeord, slik at brukerne raskt kan finne informasjonen de trenger. Selv om et hjelpefilgeneratorprogram kan opprette en indeks automatisk, anbefales det fortsatt at du oppretter en indeks manuelt ved hjelp av ofte søkte søkeord
Trinn 5. Velg det riktige dokumentasjonsverktøyet
Utskrevne manualer eller PDF -filer kan opprettes med et tekstbehandlingsprogram som Word eller et avansert tekstredigeringsprogram som FrameMaker, avhengig av filens lengde og kompleksitet. Hjelpefiler kan skrives med et hjelpefilopprettingsprogram, for eksempel RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix eller HelpServer.
Tips
- Teksten i programdokumentasjonen bør være strukturert på en slik måte at den er lett å lese. Plasser bildet så nær den aktuelle teksten som mulig. Del dokumentasjonen etter seksjoner og emner logisk. Hver seksjon eller emne skal beskrive et spesifikt problem, både oppgave- og programfunksjoner. Relaterte problemer kan forklares med lenker eller referanselister.
- Hvert av dokumentasjonsverktøyene som er beskrevet i denne artikkelen kan suppleres med et skjermbildeprogram, for eksempel SnagIt hvis dokumentasjonen krever flere skjermbilder. Som all annen dokumentasjon, bør du også inkludere skjermbilder for å forklare hvordan appen fungerer, i stedet for å "lokke" brukeren.
- Å være oppmerksom på stil er veldig viktig, spesielt hvis du skriver programvaredokumentasjon for sluttbrukere. Adresser brukere med pronomenet "du", i stedet for "bruker".
