Bra programvarudokumentation, oavsett om det är specifikationsdokumentation för programmerare och testare, tekniska dokument för interna användare, eller manualer och hjälpfiler för slutanvändare, hjälper användarna att förstå programvarans funktioner och funktioner. Bra dokumentation är specifik, tydlig och relevant dokumentation med all information som användaren behöver. Denna artikel hjälper dig att skriva programvarudokumentation för tekniska användare och slutanvändare.
Steg
Metod 1 av 2: Skrivning av programvarudokumentation för tekniska användare
Steg 1. Vet vilken information som ska ingå
Specifikationsdokumentet används som referenshandbok för gränssnittsdesigners, programmerare som skriver kod och testare som verifierar programvarans prestanda. Informationen som måste inkluderas beror på vilket program som skapas, men kan innehålla följande:
- Viktiga filer i programmet, till exempel filer som skapats av utvecklingsteamet, databaser som öppnas medan programmet körs och tredjepartsprogram.
- Funktioner och underrutiner, inklusive en förklaring av användningen av funktionen/subrutinen, in- och utgångsvärden.
- Programvariabler och konstanter, och hur de används.
- Övergripande programstruktur. För enhetsbaserade program kan du behöva beskriva varje modul och bibliotek. Eller om du skriver en manual för ett webbaserat program kan du behöva förklara vilka filer varje sida använder.
Steg 2. Bestäm vilken nivå av dokumentation som ska finnas och kan skiljas från programkoden
Ju mer teknisk dokumentation som ingår i programkoden, desto lättare blir det att uppdatera och underhålla den, samt att förklara de olika versionerna av programmet. Åtminstone bör dokumentationen i programkoden innehålla användning av funktioner, subrutiner, variabler och konstanter.
- Om din källkod är lång kan du skriva dokumentation i en hjälpfil, som sedan kan indexeras eller sökas med vissa nyckelord. Separata dokumentationsfiler är användbara om programlogiken är uppdelad på flera sidor och innehåller supportfiler, till exempel ett webbprogram.
- Vissa programmeringsspråk (som Java, Visual Basic. NET eller C#) har sina egna koddokumentationsstandarder. I sådana fall följer du standarddokumentationen som måste ingå i källkoden.
Steg 3. Välj lämpligt dokumentationsverktyg
I vissa fall bestäms dokumentationsverktyget av programmeringsspråket som används. Språken C ++, C#, Visual Basic, Java, PHP och andra har egna dokumentationsverktyg. Men om inte, beror verktygen som används på den dokumentation som krävs.
- En ordbehandlare som Microsoft Word är lämplig för att skapa dokumenttextfiler, så länge dokumentationen är kortfattad och enkel. För att skapa lång dokumentation med komplex text väljer de flesta tekniska författare ett specialiserat dokumentationsverktyg, till exempel Adobe FrameMaker.
- Hjälpfiler för att dokumentera källkoden kan skapas med ett stödgeneratorprogram, till exempel RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare eller HelpLogix.
Metod 2 av 2: Dokumentation för skrivprogramvara för slutanvändare
Steg 1. Känn till de affärsskäl som ligger till grund för skapandet av manualen
Även om huvudorsaken till programvarudokumentation är att hjälpa användare att förstå hur de använder programmet, finns det flera andra skäl som kan ligga till grund för skapandet av dokumentation, till exempel att hjälpa marknadsavdelningen att sälja applikationen, förbättra företagets image och minska tekniskt stöd kostar. I vissa fall krävs dokumentation för att följa föreskrifter eller andra lagkrav.
Dokumentation är dock inte ett bra substitut för ett gränssnitt. Om en applikation kräver mycket dokumentation för att fungera, bör den vara utformad för att vara mer intuitiv
Steg 2. Känn dokumentgruppens målgrupp
I allmänhet har mjukvaruanvändare begränsad datakunskap utöver de applikationer som används av dem. Det finns flera sätt att tillgodose deras dokumentationsbehov:
- Var uppmärksam på titeln på programvaran. Till exempel förstår systemadministratören i allmänhet olika datorprogram, medan sekreteraren bara känner till de applikationer som han använder för att mata in data.
- Var uppmärksam på programvaran användare. Även om deras positioner i allmänhet är kompatibla med de utförda uppgifterna, kan dessa positioner ha olika arbetsbelastning, beroende på verksamhetsort. Genom att intervjua potentiella användare kan du ta reda på om din bedömning av deras jobbtitel är korrekt.
- Var uppmärksam på befintlig dokumentation. Programvarufunktionalitetsdokumentation och specifikationer kan visa vad användarna behöver veta för att kunna använda dem. Kom dock ihåg att användarna kanske inte är intresserade av att känna till programmets "inre".
- Vet vad som krävs för att slutföra en uppgift och vad som krävs innan du kan slutföra den.
Steg 3. Bestäm lämpligt format för dokumentationen
Programvarudokumentation kan ordnas i 1 eller 2 format, nämligen referensböcker och manualer. Ibland är det en bra lösning att kombinera de två formaten.
- Referensformat används för att beskriva alla programvarufunktioner, såsom knappar, flikar, fält och dialogrutor, och hur de fungerar. Vissa hjälpfiler skrivs i detta format, särskilt de som är kontextkänsliga. När användaren klickar på Hjälp i en viss skärm får användaren relevant ämne.
- Det manuella formatet används för att förklara hur man gör något med programvaran. Manualer finns i allmänhet i tryck eller PDF -format, även om vissa hjälpsidor också innehåller instruktioner om hur man gör vissa saker. (I allmänhet är manuella format inte kontextkänsliga, men kan vara länkade från sammanhangskänsliga ämnen). Handböcker är i allmänhet i form av en guide, med en sammanfattning av de uppgifter som ska utföras i en beskrivning och en guide formaterad i steg.
Steg 4. Bestäm vilken typ av dokumentation
Programvarudokumentation för användare kan förpackas i ett eller flera av följande format: tryckta manualer, PDF -filer, hjälpfiler eller onlinehjälp. Varje typ av dokumentation är utformad för att visa dig hur du använder programvarans funktioner, oavsett om det är en guide eller en handledning. Online dokumentation och hjälpsidor kan också innehålla demonstrationsvideor, text och statiska bilder.
Online -hjälp- och supportfiler bör indexeras och sökas med hjälp av nyckelord så att användare snabbt kan hitta den information de behöver. Även om en hjälpfilgenerator kan skapa ett index automatiskt, rekommenderas det fortfarande att du skapar ett index manuellt med vanliga sökord
Steg 5. Välj lämpligt dokumentationsverktyg
Utskrivna manualer eller PDF -filer kan skapas med ett ordbehandlingsprogram som Word eller en avancerad textredigerare som FrameMaker, beroende på filens längd och komplexitet. Hjälpfiler kan skrivas med ett hjälpfilskapande program, till exempel RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix eller HelpServer.
Tips
- Texten i programdokumentationen bör vara uppbyggd så att den är lättläst. Placera bilden så nära lämplig text som möjligt. Dela upp dokumentationen efter avsnitt och ämnen logiskt. Varje avsnitt eller ämne bör beskriva ett specifikt problem, både uppgifts- och programfunktioner. Relaterade problem kan förklaras med länkar eller referenslistor.
- Var och en av de dokumentationsverktyg som beskrivs i den här artikeln kan kompletteras med ett skärmdumpprogram, till exempel SnagIt om din dokumentation kräver flera skärmdumpar. Liksom all annan dokumentation bör du också inkludera skärmdumpar för att förklara hur appen fungerar, snarare än att "locka" användaren.
- Att uppmärksamma stil är mycket viktigt, särskilt om du skriver programvarudokumentation för slutanvändare. Adressera användare med pronomenet "du", istället för "användare".
