Hvordan å skrive programvare dokumentasjon

Skrive programvare dokumentasjon for tekniske brukere

1. 1
   Bestem hvilken informasjon som må inkluderes. Programvare spesifikasjonen dokumenterer tjene som referanse manualer for designere av brukergrensesnittet, programmerere som skriver koden, og testere som bekrefter at programvaren fungerer som forutsatt. Den eksakte informasjonen er avhengig av det aktuelle programmet, men kan inneholde noen av følgende:
   • Viktige filer i programmet. Dette kan inkludere filer opprettet av utviklingsteamet, databaser nås i løpet av programmets drift, og tredjeparts støtteprogrammer.
   • Funksjoner og subrutiner. Dette inkluderer en forklaring på hva hver funksjon eller subrutine gjør, inkludert sitt utvalg av input verdier og utgang verdier.
   • Program variabler og konstanter og hvordan de blir brukt i programmet.
   • Det samlede programmet struktur. For en plate-basert program, kan dette bety beskriver programmets individuelle moduler og biblioteker, mens for en web-applikasjon, kan dette bety beskriver hvilke sider bruker hvilke filer.
2. 2
   Bestemme hvor mye av dokumentasjonen skal være innenfor programkode og hvor mye bør være atskilt fra den. Jo mer teknisk dokumentasjon er utviklet innenfor programmets kildekode til å begynne med, jo lettere vil det være å oppdatere og vedlikeholde sammen med koden, samt å dokumentere ulike versjoner av den opprinnelige søknaden. På et minimum, må dokumentasjon i kildekoden til å forklare hensikten med funksjoner, subrutiner, variabler og konstanter.
   • Hvis kildekoden er spesielt lang, kan det dokumenteres i form av en hjelp fil, som kan indekseres eller søkte med søkeord. Dette er en spesiell fordel for anvendelser hvor programmet logikk er fragmentert over mange sider og omfatter en rekke supplerende filer, som med visse web-applikasjoner.
   • Noen programmeringsspråk, for eksempel Java og. NET Framework (Visual Basic.NET, C #), har sine egne standarder for dokumentasjon av kode. I disse tilfellene følge standardene for hvor mye av dokumentasjonen skal være inkludert i kildekoden.
3. 3
   Velg riktig dokumentasjon verktøyet. Til en viss grad, er dette bestemt av språket koden er skrevet i, det være seg C + +, C #, Visual Basic, Java, eller PHP, som spesifikke verktøy finnes for disse og andre språk. I andre tilfeller er verktøyet for å bruke bestemmes av typen av nødvendig dokumentasjon.
   • Tekstbehandlingsprogrammer for Microsoft Word er tilstrekkelig for å skape separate tekstfiler med dokumentasjon, så lenge dokumentasjonen er ganske kort og enkel. For lange, komplekse tekstfiler, mange tekniske forfattere foretrekker en dokumentasjon verktøy som Adobe FrameMaker.
   • Hjelp filer for å dokumentere kildekoden kan bli produsert med hjelp authoring verktøy, for eksempel RoboHelp, Hjelp og Manual, Doc-To-Help, madcap Flare, eller HelpLogix.

Skrive programvare dokumentasjon for sluttbrukere

1. 1
   Bestem forretningsmessige årsaker for dokumentasjonen. Selv om funksjonell grunn til å dokumentere programvare er å hjelpe brukerne med å forstå hvordan du bruker programmet, det er andre grunner også, som for eksempel å bistå i markedsføring av programvare, styrke selskapets image, og spesielt, noe som reduserer kostnadene til teknisk støtte. I noen tilfeller er dokumentasjon som er nødvendig for å overholde visse regler eller andre juridiske krav.
   • Ikke i noe tilfelle, derimot, bør dokumentasjonen for programvaren erstatning for dårlig grensesnitt design. Hvis et program skjermen krever store mengder dokumentasjon for å forklare det, bedre å endre skjermbildet design til noe mer intuitivt.
2. 2
   Forstå publikum du skriver dokumentasjonen for. I de fleste tilfeller, programvare brukere har liten kunnskap om datamaskiner utenfor de oppgavene de programmene de bruker gjør dem i stand til å gjøre. Det er flere måter å finne ut hvordan de skal løse sine behov med dokumentasjonen.
   • Se på stillingstitler dine potensielle brukere holder. Et system administrator er sannsynlig ekspert med en rekke programmer, mens en dataregistrering kontorist er mer sannsynlig å vite bare programmet han eller hun i dag bruker til å legge inn data.
   • Se på brukerne selv. Selv stillingstitler generelt indikerer gjøre hva folk kan det være stor variasjon i hvordan enkelte titler brukes innen en gitt organisasjon. Ved å intervjue potensielle brukere, kan du få en følelse for om ditt inntrykk av hva deres jobb tittelen indikerer er korrekt eller ikke.
   • Se på eksisterende dokumentasjon. Dokumentasjon for tidligere versjoner av programvaren, samt funksjonelle spesifikasjoner, gi noen indikasjon på hva brukeren trenger å vite for å bruke programmet. Husk imidlertid at sluttbrukerne ikke er så interessert i hvordan programmet fungerer som de er i hva den kan gjøre for dem.
   • Identifisere de oppgavene som trengs for å gjøre jobben, og hvilke oppgaver må gjøres før disse oppgavene kan gjøres.
3. 3
   Bestemme riktig format (er) for dokumentasjon. Dokumentasjonen for programvaren kan være strukturert på en av to formater, referansen manuelle og brukerveiledningen. Noen ganger, er en kombinasjon av formater den beste tilnærmingen.
   • En referanse manuelt format er viet til å forklare de enkelte funksjoner i et program (knapper, kategorier feltet, og dialogboksen) og hvordan de fungerer. Mange hjelpefiler er skrevet i dette formatet, spesielt kontekstavhengig hjelp som viser et relevant tema når en bruker klikker på Hjelp-knappen på en bestemt skjerm.
   • En brukerhåndboken format forklarer hvordan du bruker programvaren til å utføre en bestemt oppgave. Bruksanvisninger er ofte formatert som trykte guider eller PDF-filer, selv om noen hjelpefiler omfatter temaer som hvordan å utføre bestemte oppgaver. (Disse emnene er vanligvis ikke kontekstavhengig, selv om de kan bli hyperkoblet til fra emner som er.) Bruksanvisninger ofte ta form av opplæring, med et sammendrag av de oppgavene som skal utføres i innledningen og instruksene i nummererte trinn.
4. 4
   Bestem hvilken form (s) dokumentasjonen bør ta. Dokumentasjonen for programvaren for sluttbrukere kan ta en eller flere av mange former: trykte håndbøker, PDF-dokumenter, hjelpefiler, eller hjelpen. Hver form er utformet for å vise brukeren hvordan du bruker hver av programmets funksjoner, enten i form av en gjennomgang eller en tutorial, i tilfelle av hjelpefiler og hjelpen, kan dette omfatte demonstrasjon videoer, samt tekst og stillbilder.
   • Hjelpefiler og elektroniske hjelpen skal indekseres og søkeord-søkbar å tillate brukere å raskt finne den informasjonen de leter etter. Selv om hjelp fil redigeringsverktøy kan generere indekser automatisk, er det ofte bedre å opprette indeksen manuelt, med vilkår brukere sannsynligvis vil søke etter.
5. 5
   Velg riktig dokumentasjon verktøyet. Trykt eller PDF brukermanualer kan skrives med et tekstbehandlingsprogram som Word eller et avansert tekst-editor som FrameMaker, avhengig av lengde og kompleksitet. Hjelp filer kan skrives med en hjelp forfatterverktøy som RoboHelp, Hjelp og Manual, Doc-To-Help, Flare, eller HelpLogix.