Hur man skriver programvara dokumentation

Skriva programvara dokumentation för tekniska användare

1. 1
   Bestäm vilken information som måste ingå. Programvara specifikationsdokumenten tjäna som referens manualer för designers av användargränssnitt, programmerare som skriver koden, och testare som verifierar att programmet fungerar som avsett. Den exakta informationen beror på programmet i fråga, men kan omfatta något av följande:
   • Viktiga filer i programmet. Detta kan inkludera filer som skapats av utvecklingsgruppen, databaser nås under programmets verksamhet, och utomstående hjälpprogram.
   • Funktioner och subrutiner. Detta inkluderar en förklaring av vad varje funktion eller subrutin gör, inklusive dess utbud av ingångsvärden och utgående värdena.
   • Program variabler och konstanter, och hur de används i ansökan.
   • Den övergripande programstruktur. För en skiva-baserat program, kan detta betyda att beskriva programmets enskilda moduler och bibliotek, medan det för en webbapplikation, kan detta betyda att beskriva vilka sidor använder vilka filer.
2. 2
   Bestäm hur mycket av dokumentationen bör vara inom programkod och hur mycket ska vara skild från det. Den mer tekniska dokumentationen utvecklas inom programmets källkod till att börja med, desto lättare blir det att uppdatera och underhålla tillsammans med koden, samt att dokumentera olika versioner av den ursprungliga ansökan. På ett minimum, behöver dokumentation inom källkoden för att förklara syftet med funktioner, subrutiner, variabler och konstanter.
   • Om källkoden är särskilt lång, kan det dokumenteras i form av en hjälpfil, som kan indexeras eller sökt med sökord. Detta är en särskild fördel för applikationer där programmets logik är fragmenterad över många sidor och innehåller ett antal kompletterande filer, som med vissa webbapplikationer.
   • Vissa programmeringsspråk, som Java och. NET Framework (Visual Basic.NET, C #), har sina egna standarder för att dokumentera koden. I dessa fall, följa de normer för hur mycket av den dokumentation som bör ingå i källkoden.
3. 3
   Välj lämplig dokumentationshjälpmedel. Till viss del är detta bestäms av språk koden är skriven på, vare sig det C + +, C #, Visual Basic, Java eller PHP, som särskilda verktyg finns för dessa och andra språk. I andra fall är verktyget att använda avgörs av vilken typ av dokumentation som krävs.
   • Ordbehandlingsprogram för Microsoft Word är tillräckliga för att skapa separata textfiler på dokumentation, så länge som dokumentationen är ganska kort och enkel. För långa, komplexa textfiler, många tekniska skribenter föredrar dokumentationshjälpmedel som Adobe FrameMaker.
   • Hjälpfilerna för dokumentera källkod kan produceras med all hjälp författarverktyg, såsom RoboHelp, Hjälp och manuell, Doc-To-Help, MadCap Flare, eller HelpLogix.

Skriva programvara dokumentation för slutanvändare

1. 1
   Bestäm affärsmässiga skälen för din dokumentation. Även den funktionella skäl för att dokumentera programvara är att hjälpa användarna att förstå hur man använder programmet, det finns andra orsaker också, t.ex. att bistå i marknadsföringen av programmet, förbättra företagets image, och framför allt, minska tekniska kostnader för support. I vissa fall är dokumentation som behövs för att uppfylla särskilda regler eller andra rättsliga krav.
   • I inget fall får dock programvara dokumentation substitut för dålig gränssnittsdesign. Om ett program skärm kräver mängder av dokumentation för att förklara det, bättre att ändra skärmens design till något mer intuitivt.
2. 2
   Förstå publiken du skriver dokumentation för. I de flesta fall, programvara användare har liten kunskap om datorer utanför de uppgifter de applikationer de använder gör det möjligt för dem att göra. Det finns flera sätt att avgöra hur man ska hantera sina behov med din dokumentation.
   • Titta på titlar dina potentiella användarna har. En systemadministratör är sannolikt expert med ett antal programvaror, medan en datainmatning kontorist är mer benägna att veta bara programmet han eller hon för närvarande använder för att mata in data.
   • Titta på användarna själva. Även titlar generellt ange vad folk gör, kan det finnas stora skillnader i hur vissa titlar används inom en viss organisation. Genom att intervjua presumtiva användare, kan du få en känsla för om dina intryck av vad deras jobb titeln anger är korrekta eller inte.
   • Titta på befintlig dokumentation. Dokumentation för tidigare versioner av programvaran, samt funktionella specifikationer, ger en fingervisning om vad användaren behöver veta för att använda programmet. Tänk dock att slutanvändarna inte är så intresserade av hur programmet fungerar som de är i vad den kan göra för dem.
   • Identifiera de uppgifter som behövs för att göra jobbet, och vilka uppgifter behöver göras innan dessa uppgifter kan göras.
3. 3
   Bestäm lämpligt format (er) för dokumentation. Programvara dokumentation kan struktureras i 1 av 2 format, Reference Manual och bruksanvisningen. Ibland är en kombination av format den bästa metoden.
   • En referens manuellt format ägnas åt att förklara de olika funktionerna i ett program (knappen, fliken, fält, och dialogrutan) och hur de fungerar. Många hjälpfiler är skrivna i detta format, särskilt sammanhangsberoende hjälp som visar ett relevant ämne när en användare klickar på knappen Hjälp på en viss skärm.
   • En bruksanvisning format förklarar hur du använder programvaran för att utföra en viss uppgift. Användarguider ofta formateras som tryckta guider eller PDF-filer, även om vissa hjälpfiler ämnen som handlar om hur man utför särskilda uppgifter. (Dessa hjälpavsnitt är oftast inte sammanhangsberoende, även om de kan hyperlänk till från ämnen som är.) Användarguider tar ofta formen av handledning, med en sammanfattning av de uppgifter som skall utföras i inledningen och instruktionerna i numrerade steg.
4. 4
   Bestäm vilken form (er) dokumentationen bör ta. Programvara dokumentation för slutanvändare kan ta en eller flera av många former: tryckta manualer, PDF-dokument, hjälpfiler eller direkthjälp. Varje blankett är utformad för att visa användaren hur man använder alla programmets funktioner, vare sig i form av en genomgång eller en tutorial, i fallet med hjälpfiler och direkthjälp, kan detta inkludera demonstrationsvideor samt text och fortfarande grafik.
   • Hjälp-filer och direkthjälp bör indexeras och nyckelordet-sökbara att tillåta användare att snabbt hitta den information de letar efter. Även hjälpfilen författarverktyg kan generera index automatiskt, är det ofta bättre att skapa index manuellt, med hjälp av termer användarna sannolikt kommer att söka efter.
5. 5
   Välj lämplig dokumentationshjälpmedel. Tryckt eller PDF bruksanvisningar kan skrivas med ett ordbehandlingsprogram som Word eller en sofistikerad textredigerare som FrameMaker, beroende på deras längd och komplexitet. Hjälp-filer kan skrivas med en hjälp författarverktyg som RoboHelp, Hjälp och manuell, Doc-To-Help, Flare, eller HelpLogix.