Hur skriver jag programdokumentation?
Nedan följer instruktioner om hur man skriver programvarudokumentation för tekniska användare och slutanvändare.
Bra programdokumentation, oavsett om det finns ett specifikationsdokument för programmerare och testare, ett tekniskt dokument för interna användare eller programvaruhandböcker och hjälpfiler för slutanvändare, hjälper den som arbetar med programvaran att förstå dess funktioner och funktioner. God programdokumentation är specifik, kortfattad och relevant och ger all information som är viktig för den person som använder programvaran. Nedan följer instruktioner om hur man skriver programvarudokumentation för tekniska användare och slutanvändare.
Metod 1 av 2: skriva programdokumentation för tekniska användare
- 1Bestäm vilken information som behöver inkluderas. Programvaruspecifikationsdokument fungerar som referenshandböcker för designare av användargränssnittet, programmerare som skriver koden och testare som verifierar att programvaran fungerar som avsett. Den exakta informationen beror på programmet i fråga men kan innehålla något av följande:
- Nyckelfiler i applikationen. Detta kan inkludera filer som skapats av utvecklingsteamet, databaser som nås under programmets drift och verktyg från tredje part.
- Funktioner och underrutiner. Detta inkluderar en förklaring av vad varje funktion eller underrutin gör, inklusive dess intervall för ingångsvärden och utgångsvärden.
- Programvariabler och konstanter och hur de används i applikationen.
- Den övergripande programstrukturen. För en skivbaserad applikation kan det innebära att beskriva programmets individuella moduler och bibliotek, medan det för en webbapplikation kan innebära att beskriva vilka sidor som använder vilka filer.
- 2Bestäm hur mycket av dokumentationen som ska ligga inom programkoden och hur mycket som ska vara separat från den. Ju mer teknisk dokumentation 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 applikationen. Dokumentation inom källkoden måste åtminstone förklara syftet med funktioner, underrutiner, variabler och konstanter.
- Om källkoden är särskilt lång kan den dokumenteras i form av en hjälpfil som kan indexeras eller sökas med nyckelord. Detta är en speciell fördel för applikationer där programlogiken är fragmenterad över många sidor och innehåller ett antal kompletterande filer, som med vissa webbapplikationer.
- Vissa programmeringsspråk, till exempel Java och. NET Framework (Visual Basic.NET, C #), har sina egna standarder för att dokumentera kod. Följ i dessa fall standarderna för hur mycket av dokumentationen som ska ingå i källkoden.
Programvarudokumentation för slutanvändare kan ta en eller flera av många former: tryckta manualer, PDF-dokument, hjälpfiler eller onlinehjälp. - 3Välj lämpligt dokumentationsverktyg. Till viss del bestäms detta av språket som koden är skriven på, vare sig det är C ++, C #, Visual Basic, Java eller PHP, eftersom det finns specifika verktyg för dessa och andra språk. I andra fall bestäms verktyget som ska användas av vilken typ av dokumentation som krävs.
- Ordbehandlingsprogram för Microsoft Word är tillräckliga för att skapa separata dokumentfiler, så länge dokumentationen är ganska kort och enkel. Under långa, komplexa textfiler föredrar många tekniska författare ett dokumentationsverktyg som Adobe FrameMaker.
- Hjälpfiler för att dokumentera källkod kan produceras med vilket hjälpverktyg som helst, t.ex. RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare eller HelpLogix.
Metod 2 av 2: skriva programdokumentation för slutanvändare
- 1Bestäm affärsskälen för din dokumentation. Även om det funktionella skälet för att dokumentera programvara är att hjälpa användarna att förstå hur man använder applikationen, finns det också andra skäl, till exempel att hjälpa till med marknadsföring av programvaran, förbättra företagets image och framför allt att sänka kostnaderna för teknisk support. I vissa fall är dokumentation nödvändig för att följa vissa föreskrifter eller andra rättsliga krav.
- I inget fall bör dock programvarudokumentation ersätta dålig gränssnittsdesign. Om en applikationsskärm kräver massor av dokumentation för att förklara det, är det bättre att ändra skärmdesignen till något mer intuitivt.
- 2Förstå publiken du skriver dokumentationen för. I de flesta fall har programvaruanvändare liten kunskap om datorer utanför de uppgifter applikationerna de gör det möjligt för dem att göra. Det finns flera sätt att avgöra hur man ska hantera deras behov med din dokumentation.
- Titta på de jobbtitlar dina potentiella användare innehar. En systemadministratör är sannolikt expert med ett antal program, medan en datainmatare är mer benägna att bara känna till det program som han eller hon för närvarande använder för att mata in data.
- Titta på användarna själva. Även om arbetstitlar i allmänhet anger vad människor gör kan det finnas stora variationer i hur vissa titlar används inom en viss organisation. Genom att intervjua potentiella användare kan du få en känsla för om dina intryck av vad deras anställningstitel anger är korrekta eller inte.
- Titta på befintlig dokumentation. Dokumentation för tidigare versioner av programvaran, liksom funktionella specifikationer, ger en viss indikation på vad användaren behöver veta för att använda programmet. Tänk dock på att slutanvändarna inte är lika intresserade av hur programmet fungerar som vad de kan göra för dem.
- Identifiera de uppgifter som behövs för att utföra jobbet och vilka uppgifter som måste utföras innan dessa uppgifter kan utföras.
God programdokumentation är specifik, kortfattad och relevant och ger all information som är viktig för den person som använder programvaran. - 3Bestäm lämpligt format för dokumentationen. Mjukvarudokumentation kan struktureras i ett av två format, referenshandboken och användarhandboken. Ibland är en kombination av format det bästa sättet.
- Ett referensmanualformat ägnas åt att förklara de enskilda funktionerna i ett program (knapp, flik, fält och dialogruta) och hur de fungerar. Många hjälpfiler skrivs i det här formatet, särskilt kontextkänslig hjälp som visar ett relevant ämne när en användare klickar på hjälpknappen på en viss skärm.
- Ett användarhandbokformat förklarar hur man använder programvaran för att utföra en viss uppgift. Användarhandböckerna formateras ofta som tryckta guider eller PDF-filer, även om vissa hjälpfiler innehåller ämnen om hur man utför vissa uppgifter. (Dessa hjälpämnen är vanligtvis inte sammanhangskänsliga, även om de kan hyperlänkas till ämnen som är.) Användarhandböckerna har ofta form av handledning, med en sammanfattning av de uppgifter som ska utföras i introduktionen och instruktioner i numrerade steg.
- 4Bestäm vilken eller vilka former dokumentationen ska ha. Programvarudokumentation för slutanvändare kan ta en eller flera av många former: tryckta manualer, PDF-dokument, hjälpfiler eller onlinehjälp. Varje formulär är utformat för att visa användaren hur man använder var och en av programmets funktioner, antingen i form av en genomgång eller en handledning; i fallet med hjälpfiler och onlinehjälp kan detta inkludera demonstrationsvideor samt text och stillbilder.
- Hjälpfiler och onlinehjälp bör indexeras och sökas med nyckelord så att användare snabbt kan hitta den information de letar efter. Även om verktyg för redigering av hjälpfiler kan generera index automatiskt är det ofta bättre att skapa index manuellt, med hjälp av termer som användare troligen söker efter.
- 5Välj lämpligt dokumentationsverktyg. Tryckta eller PDF-användarhandböcker kan skrivas med ett ordbehandlingsprogram som Word eller en sofistikerad textredigerare som FrameMaker, beroende på deras längd och komplexitet. Hjälpfiler kan skrivas med hjälpverktyg som RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix eller HelpServer.
Metod 2 av 2: skriva programdokumentation för slutanvändare.
- Texten bör vara ordnad för enkel läsning, med grafik placerad så nära texten som hänvisar till dem som möjligt. Dela upp dokumentationen i sektioner och ämnen logiskt. Varje avsnitt eller ämne bör ta itu med en enda fråga, vare sig det är en enskild programfunktion eller uppgift. Relaterade problem kan hanteras med "se även" listor eller hyperlänkar efter behov.
- Vilket som helst av dokumentationsverktygen som listas ovan kan kompletteras med ett skärmdump-skapande program, till exempel Snagit, om dokumentationen kräver ett antal skärmdumpar. Som med annan dokumentation bör skärmdumpar inkluderas för att förklara hur programvaran fungerar, inte för att blända användaren.
- Ton är särskilt viktig, särskilt när man skriver programvarudokumentation för slutanvändare. Adressera användare med den andra personen "du" istället för tredje person "användare."
- Programvarudokumentationsverktyg / hjälp för redigeringsverktyg
- Skärmdump-skapande verktyg
Läs också: Hur undviker man vanliga stavfel?
Frågor och svar
- Jag har sett tangenttryckningar dokumenterade i flera format. Finns det en faktisk standard för artiklar eller är de olika?Det finns ingen universell standard; Det är dock en bra idé att sätta en standard för dina egna dokument. För ett par idéer, se Microsoft Manual of Style (tillgänglig på Amazon) och Apple Style Guide (help.apple.com/applestyleguide/). De har olika stilar, så om du skriver dokumentation över flera plattformar kan det hända att du använder vissa element från en guide och andra från en annan.
- Finns det några kostnadsfria verktyg för programdokumentation?Försök med Doxygen. Du kommenterar din kod, kör Doxygen och du har en webbsida. Lägg till LaTeX så har du en PDF.
