HodTari.com

Sådan skriver du Software Documentation

God software dokumentation - hvad enten det er til programmører og testere, til tekniske dokumenter fra interne brugere eller til software manualer og hjælpefiler til slutbrugere - hjælper den person, der arbejder med softwaren, for at forstå sine funktioner og egenskaber. God dokumentation er specifik, kortfattet og relevant og giver alle vigtige oplysninger til personer, der bruger programmet. Fortsæt læsning for instruktioner om, hvordan du skriver software dokumentation til tekniske og endelige brugere.

trin

Metode 1
Skrivning af softwaredokumentation til tekniske brugere

Billede med titlen Skriv Software Documentation Trin 1
1
Bestem hvilke oplysninger der skal medtages. Softwarespecifikationsdokumenter tjener som referencemanualer til UI-designere, kodeskrivende programmører og testere, der verificerer, at softwaren virker som beregnet. Den nøjagtige information afhænger af det pågældende program, men kan omfatte:
  • Nøglefiler i applikationen. De kan omfatte filer, der er oprettet af udviklingsholdet, databaser, der er adgang til under programoperationen og tredjepartsværktøjer.
  • Funktioner og underrutiner. Her indgår en forklaring på, hvad hver funktion eller subrutine gør, herunder dets række af input- og outputværdier.
  • Variabler og programkonstanter, og hvordan de anvendes i applikationen.
  • Den generelle struktur af programmet. For en diskbaseret applikation kan det betyde at beskrive de enkelte moduler og biblioteker i programmet, mens det for en webapplikation er en beskrivelse af hvilke sider der bruger hvilke filer.
  • Billede med titlen Skriv Software Documentation Trin 2

    Video: The Code: Story of Linux documentary (MULTiSUB)

    2
    Bestem, hvor meget dokumentation skal være inde i programkoden, og hvor meget der skal skilles fra det. Jo mere teknisk dokumentation er udviklet inden for programkilden, jo lettere vil det være at opretholde og vedligeholde koden samt dokumentere de forskellige versioner af den oprindelige ansøgning. I det mindste skal dokumentation i kildekoden forklare formålet med funktionerne, subrutinerne, variablerne og konstanterne.
    • Hvis kildekoden er særlig lang, kan den dokumenteres i form af en hjælpefil, som kan indekseres eller søges med søgeord. Dette er en særlig fordel for applikationer, hvor programlogikken er fragmenteret på mange sider og indeholder flere supplerende filer samt visse webapplikationer.
    • Nogle programmeringssprog, som Java og .NET Framework (Visual Basic .NET, C #), har deres egne programmer til dokumentation af kode. I sådanne tilfælde skal du følge standarderne for mængden af ​​dokumentation, der skal medtages.
  • Billede med titlen Skriv Software Documentation Trin 3
    3
    Vælg det rigtige dokumentationsværktøj. Dette bestemmes i et vist omfang af det sprog, hvor koden er skrevet, enten i C ++, C #, Visual Basic, Java eller PHP, da der findes specifikke værktøjer til disse og andre sprog. I andre tilfælde bestemmes det værktøj, der skal bruges, af den krævede dokumentation.
    • Ordbehandlingsprogrammer til Microsoft Word er egnede til at oprette separate tekstfiler, så længe dokumentationen er relativt kort og enkel. For lange og komplekse tekstfiler foretrækker mange tekniske forfattere et dokumentationsværktøj, som f.eks. Adobe FrameMaker.
    • Hjælpefiler til dokumentation af kildekode kan produceres med ethvert hjælpeskrivningsværktøj som RoboHelp, Hjælp og Manual, Doc-To-Help, MadCap Flare eller HelpLogix.

    • Metode 2
    Skrive software dokumentation til slutbrugere

    Billede med titlen Skriv Software Documentation Trin 4
    1
    Bestem forretningsformål med dokumentation. Selvom grunden til dette er at hjælpe brugerne med at forstå, hvordan man bruger applikationen, er der også andre grunde, som f.eks. At hjælpe med at reklamere for programmet, forbedre virksomhedens image og, vigtigst af alt, reducere supportomkostninger. I nogle tilfælde kræves dokumentation for at overholde visse regler eller andre lovkrav.
    • Under ingen omstændigheder bør dokumentationen erstatte et dårligt interface design. Hvis en applikationsskærm kræver sider og sider med dokumentation for at forklare det, er det bedre at ændre designet for at gøre det mere intuitivt.


  • Billede med titlen Skriv Software Documentation Trin 5
    2
    Forstå det publikum, som du skriver dokumentationen til. I de fleste tilfælde har softwarebrugere lidt viden om andre computere end de opgaver, de anvendelser, de bruger, tillader. Der er flere måder at bestemme, hvordan du kan opfylde dine behov med din dokumentation.
    • Bemærk jobnavne for potentielle brugere. En systemadministrator vil sandsynligvis være dygtig i en række softwareapplikationer, mens en dataindtastning sandsynligvis kun ved det program, han bruger til at indtaste data.
    • Overhold brugerne selv. Mens medarbejdertitler ofte angiver, hvad folk gør, kan der være stor variation i, hvordan visse titler anvendes inden for en bestemt organisation. Ved at interviewe potentielle brugere kan du finde ud af, om dine indtryk af dine behov er korrekte eller ej.
    • Se på den eksisterende dokumentation. Dokumentation af tidligere versioner af softwaren samt funktionelle specifikationer giver en vis indikation af, hvad brugeren skal vide for at bruge programmet. Husk dog, at slutbrugerne ikke er interesserede i, hvordan programmet fungerer, men snarere hvad det kan gøre for dem.
    • Identificer de opgaver, der er nødvendige for at udføre jobbet, og hvilke opgaver der skal udføres før jobbet.

  • Video: A Tour of Programming on Khan Academy

    Billede med titlen Skriv Software Documentation Trin 6
    3
    Bestem de relevante formater til dokumentationen. Softwaredokumentationen kan struktureres i 1 eller 2 formater, referencevejledningen og brugervejledningen. Nogle gange er en kombination af formater den bedste tilgang.
    • Et referencemanualformat er afsat til at forklare de enkelte karakteristika for en applikation (knapper, faner, felter og dialogbokse) og hvordan de virker. Mange hjælpefiler er skrevet i dette format, som viser et relevant emne, når en bruger klikker på hjælpeknappen på en bestemt skærm.
    • Et brugervejledning format forklarer, hvordan du bruger programmet til at udføre en bestemt opgave. Disse vejledninger udskrives eller vises normalt i PDF-filer, selv om nogle hjælpefiler indeholder emner om, hvordan du gør bestemte opgaver (disse hjælpeemner er generelt kontekstfølsomme, selvom de muligvis indeholder links til emner, der er). Brugervejledninger tager i almindelighed form af vejledninger med et resumé af de opgaver, der skal udføres i introduktionen og instruktionerne i de nummererede trin.
  • Billede med titlen Skriv Software Documentation Trin 7
    4
    Bestem hvilke former dokumentation skal tage. Software dokumentation til slutbrugere kan tage en af ​​flere former: trykte manualer, PDF-dokumenter, hjælpefiler eller onlinehjælp. Hver formular er lavet til at vise brugeren, hvordan man bruger hvert af programmets funktioner, enten i form af gennemgang eller tutorial - i tilfælde af hjælpefiler og onlinehjælp kan man inkludere demovideoer samt tekst og billeder.
    • Hjælpefiler skal indekseres og søges med søgeord, så brugerne finder de oplysninger, de ønsker hurtigt. Selvom skriveværktøjer kan generere indekser automatisk, er det bedst at gøre det manuelt ved hjælp af udtryk, som brugerne sandsynligvis vil søge.
  • Billede med titlen Skriv Software Documentation Trin 8
    5
    Vælg det rigtige dokumentationsværktøj. Trykte eller PDF manualer kan skrives med et tekstbehandlingsprogram som Word eller en sofistikeret tekstredigerer som FrameMaker, afhængigt af deres størrelse og kompleksitet. Hjælpefiler kan skrives med et specifikt værktøj til hjælpefiler som RoboHelp, Help og Manual, Doc-To-Help, Flare, HelpLogix eller HelpServer.

    • tips

    • Teksten skal organiseres for nem læsning, med billeder placeret tæt på den tekst, der er relateret til dem. Opdel dokumentation i sektioner og emner på en logisk måde. Hvert afsnit eller emne kan henvises til med "se også" eller links efter behov.
    • Dokumentationsværktøjerne ovenfor kan suppleres med et screenshots-program, såsom Snagit, hvis dokumentationen kræver flere skærmbilleder. Som med anden dokumentation skal disse skærmbilleder medtages for at hjælpe med at forklare, hvordan programmet virker, og ikke for at imponere brugeren.
    • Tonen er særlig vigtig, især når du skriver dokumentation til slutbrugere. Kald dem "dig" i stedet for "brugere".

    Nødvendige materialer

    • Software dokumentationsværktøj / hjælpefiler
    • Skærmbilleder oprettelsesværktøj

    Kilder og citater

    Video: Arduino GSM Modülü Kümes Sıcaklık Projesi || FireBeetle & Micro Solar Power Manager

    Vis mere ... (1)
    Del på sociale netværk:

    Relaterede
    © 2024 HodTari.com