God softwaredokumentation, hvad enten det er specifikationsdokumentation til programmører og testere, tekniske dokumenter til interne brugere eller manualer og hjælpefiler til slutbrugere, hjælper brugerne med at forstå softwarens funktioner og funktioner. God dokumentation er dokumentation, der er specifik, klar og relevant, med alle de oplysninger, brugeren har brug for. Denne artikel guider dig til at skrive softwaredokumentation til tekniske brugere og slutbrugere.
Trin
Metode 1 af 2: Skrivning af softwaredokumentation til tekniske brugere
Trin 1. Ved, hvilke oplysninger der skal medtages
Specifikationsdokumentet bruges som referencehåndbog til grænseflade designere, programmører, der skriver kode, og testere, der verificerer softwarens ydeevne. De oplysninger, der skal inkluderes, afhænger af det program, der oprettes, men kan omfatte følgende:
- Vigtige filer i applikationen, f.eks. Filer, der er oprettet af udviklingsteamet, adgang til databaser, mens programmet kører, og tredjepartsapplikationer.
- Funktioner og underrutiner, herunder en forklaring på brugen af funktionen/underprogram, input- og outputværdier.
- Programvariabler og konstanter, og hvordan de bruges.
- Overordnet programstruktur. For drevbaserede programmer skal du muligvis beskrive hvert modul og bibliotek. Eller hvis du skriver en manual til et webbaseret program, skal du muligvis forklare, hvilke filer hver side bruger.
Trin 2. Beslut, hvilket dokumentationsniveau der skal være til stede og adskilt fra programkoden
Jo mere teknisk dokumentation der er inkluderet i programkoden, jo lettere bliver det at opdatere og vedligeholde den samt forklare de forskellige versioner af programmet. Dokumentationen i programkoden skal mindst indeholde brug af funktioner, underrutiner, variabler og konstanter.
- Hvis din kildekode er lang, kan du skrive dokumentation i en hjælpefil, som derefter kan indekseres eller søges med bestemte søgeord. Separate dokumentationsfiler er nyttige, hvis programlogikken er delt over flere sider og indeholder supportfiler, f.eks. Et webprogram.
- Nogle programmeringssprog (f.eks. Java, Visual Basic. NET eller C#) har deres egne kodedokumentationsstandarder. I sådanne tilfælde skal du følge standarddokumentationen, der skal indeholde kildekoden.
Trin 3. Vælg det relevante dokumentationsværktøj
I nogle tilfælde bestemmes dokumentationsværktøjet af det anvendte programmeringssprog. Sprogene C ++, C#, Visual Basic, Java, PHP og andre har deres egne dokumentationsværktøjer. Hvis ikke, afhænger de anvendte værktøjer imidlertid af den nødvendige dokumentation.
- En tekstbehandler som Microsoft Word er velegnet til oprettelse af dokumenttekstfiler, så længe dokumentationen er kortfattet og enkel. For at oprette lang dokumentation med kompleks tekst vælger de fleste tekniske forfattere et specialiseret dokumentationsværktøj, f.eks. Adobe FrameMaker.
- Hjælpfiler til dokumentation af kildekode kan oprettes med et supportfilgeneratorprogram, f.eks. RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare eller HelpLogix.
Metode 2 af 2: Skrivning af softwaredokumentation til slutbrugere
Trin 1. Kend de forretningsmæssige årsager, der ligger til grund for oprettelsen af manualen
Selvom hovedårsagen til softwaredokumentation er at hjælpe brugerne med at forstå, hvordan de bruger applikationen, er der flere andre grunde, der kan ligge til grund for oprettelsen af dokumentation, såsom at hjælpe marketingafdelingen med at sælge applikationen, forbedre virksomhedens image og reducere teknisk support omkostninger. I nogle tilfælde kræves dokumentation for at overholde regler eller andre lovkrav.
Dog er dokumentation ikke en god erstatning for en grænseflade. Hvis en applikation kræver meget dokumentation for at fungere, bør den være designet til at være mere intuitiv
Trin 2. Kend dokumentationen til målgruppen
Generelt har softwarebrugere begrænset computerkendskab ud over de applikationer, de bruger. Der er flere måder at opfylde deres dokumentationsbehov på:
- Vær opmærksom på softwarebrugerens titel. For eksempel forstår systemadministratoren generelt forskellige computerprogrammer, mens sekretæren kun kender de applikationer, han bruger til at indtaste data.
- Vær opmærksom på softwarebrugere. Selvom deres positioner generelt er kompatible med de udførte opgaver, kan disse stillinger have forskellige arbejdsbyrder afhængigt af forretningsstedet. Ved at interviewe potentielle brugere kan du finde ud af, om din vurdering af deres jobtitel er korrekt.
- Vær opmærksom på den eksisterende dokumentation. Softwarefunktionalitetsdokumentation og specifikationer kan vise, hvad brugerne skal vide for at kunne bruge dem. Husk dog, at brugerne muligvis ikke er interesseret i at kende programmets "inderste".
- Ved, hvad der skal til for at fuldføre en opgave, og hvad der skal til, før du kan fuldføre den.
Trin 3. Bestem det passende format til dokumentationen
Softwaredokumentation kan arrangeres i 1 eller 2 formater, nemlig opslagsbøger og manualer. Nogle gange er det en god løsning at kombinere de to formater.
- Referenceformater bruges til at beskrive alle softwarefunktioner, såsom knapper, faner, felter og dialogbokse, og hvordan de fungerer. Nogle hjælpefiler er skrevet i dette format, især dem, der er kontekstfølsomme. Når brugeren klikker på Hjælp på en bestemt skærm, modtager brugeren det relevante emne.
- Det manuelle format bruges til at forklare, hvordan man gør noget med softwaren. Manualer er generelt i print eller PDF -format, selvom nogle hjælpesider også indeholder instruktioner om, hvordan man gør visse ting. (Generelt er manuelle formater ikke kontekstfølsomme, men kan være knyttet fra kontekstfølsomme emner). Håndbøger er generelt i form af en vejledning med et resumé af de opgaver, der skal udføres i en beskrivelse, og en vejledning formateret i trin.
Trin 4. Beslut dig for dokumentationstypen
Softwaredokumentation til brugere kan være pakket i et eller flere af følgende formater: trykte manualer, PDF -filer, hjælpefiler eller onlinehjælp. Hver type dokumentation er designet til at vise dig, hvordan du bruger softwarens funktioner, uanset om det er en vejledning eller en tutorial. Online dokumentation og hjælpesider kan også indeholde demonstrationsvideoer, tekst og statiske billeder.
Online hjælp- og supportfiler skal indekseres og søges ved hjælp af søgeord, så brugerne hurtigt kan finde de oplysninger, de har brug for. Selvom et hjælpefilgeneratorprogram automatisk kan oprette et indeks, anbefales det stadig, at du opretter et indeks manuelt ved hjælp af almindeligt søgte søgeord
Trin 5. Vælg det relevante dokumentationsværktøj
Trykte manualer eller PDF'er kan oprettes med et tekstbehandlingsprogram som Word eller en avanceret tekstredigerer som FrameMaker, afhængigt af filens længde og kompleksitet. Hjælpfiler kan skrives med et hjælpefiloprettelsesprogram, f.eks. RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix eller HelpServer.
Tips
- Teksten i programdokumentationen skal være opbygget på en sådan måde, at den er let at læse. Placer billedet så tæt på den relevante tekst som muligt. Opdel dokumentation efter sektioner og emner logisk. Hvert afsnit eller emne skal beskrive et specifikt problem, både opgave- og programfunktioner. Relaterede spørgsmål kan forklares med links eller referencelister.
- Hvert af de dokumentationsværktøjer, der er beskrevet i denne artikel, kan suppleres med et screenshot maker -program, f.eks. SnagIt, hvis din dokumentation kræver flere skærmbilleder. Som enhver anden dokumentation bør du også inkludere skærmbilleder for at hjælpe med at forklare, hvordan appen fungerer, frem for at "lokke" brugeren.
- Det er meget vigtigt at være opmærksom på stil, især hvis du skriver softwaredokumentation til slutbrugere. Adresser brugere med pronomenet "dig", i stedet for "bruger".
