Instrucțiuni gratuite pas cu pas 
Om källkoden är särskilt lång kan den dokumenteras i form av en hjälpfil, som kan indexeras och 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 ytterligare filer, till exempel med vissa webbapplikationer. Vissa programmeringsspråk, som Java och .NET Framework (Visual Basic.NET, C#), har sina egna standarder för att dokumentera koden. Följ i dessa fall standarderna om hur mycket av dokumentationen som ska ingå i källkoden. 
Ordbehandlingsprogram för Microsoft Word räcker för att skapa separata textfiler för dokumentation, så länge dokumentationen är ganska kort och enkel. För långa, komplexa textfiler föredrar många tekniska skribenter ett dokumentationsverktyg som Adobe FrameMaker. Hjälpfiler för att dokumentera källkoden kan skapas med vilket hjälpverktyg som helst, som RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare eller HelpLogix. 
Titta på vilka funktioner dina potentiella användare har. En systemadministratör är sannolikt en expert på ett antal mjukvaruapplikationer, medan en datainmatningsarbetare sannolikt bara känner till applikationen han eller hon använder för att mata in data. Titta på användarna själva. Medan jobbtitlar vanligtvis indikerar vad människor gör, kan det finnas betydande skillnader i hur vissa positioner tillsätts inom en organisation. Genom att intervjua potentiella användare kan du få en uppfattning om huruvida ditt intryck av vad deras position indikerar är korrekt eller inte. Se befintlig dokumentation. Dokumentation för tidigare versioner av programvaran (liksom funktionsspecifikationer) ger en indikation på vad användaren behöver veta för att använda programmet. Tänk dock på att slutanvändare egentligen inte är intresserade av hur programmet fungerar, utan av vad det kan göra för dem. Bestäm de uppgifter som måste göras för att slutföra en uppgift och vilka uppgifter som måste utföras innan dessa uppgifter kan utföras. 
En referensguide ägnas åt att förklara de individuella funktionerna i ett program (knappar, flikar, fält och dialogruta) och hur de fungerar. Många hjälpfiler är skrivna i det här formatet, särskilt sammanhangskänslig hjälp som visar ett relevant ämne när en användare klickar på knappen Hjälp på en viss skärm. En användarhandbok förklarar hur du använder programvaran för att utföra en viss uppgift. Användarmanualer är ofta formaterade 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 kontextberoende, även om de kan vara länkade till ämnen som är det.) Användarguider kommer ofta i form av handledningar, med en översikt över de uppgifter som ska utföras i introduktionen och instruktioner som ges i numrerade steg. 
Hjälpfiler och onlinehjälp bör vara indexerade och sökbara med nyckelord, så att användare snabbt kan hitta den information de behöver. Även om hjälpfilbyggare automatiskt kan generera index, är det ofta bättre att skapa indexet manuellt med hjälp av termer som användare vanligtvis söker efter. 
Skriva dokumentation för programvara
Bra mjukvarudokumentation, oavsett om det är ett specifikationsdokument för programmerare och testare, ett tekniskt dokument för kollegor eller mjukvarumanualer och hjälpfiler för slutanvändare, hjälper den person som måste arbeta med programvaran att förstå alla dess egenskaper och funktioner. Bra mjukvarudokumentation är specifik, kortfattad och relevant och ger all viktig information till den som använder programvaran. Nedan hittar du instruktioner om hur du skriver mjukvarudokumentation för tekniska användare och slutanvändare.
Steg
Metod 1 av 2: Skriva mjukvarudokumentation för tekniska användare
1. Bestäm vilken information som ska inkluderas. Programvaruspecifikationer fungerar som guider för designers av användargränssnitt, 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:
- De viktigaste filerna i applikationen. Dessa kan vara filer skapade av utvecklingsteamet, databaser som nås under programdrift och tredjepartsverktyg.
- Funktioner och subrutiner. Detta inkluderar en förklaring av vad varje funktion eller subrutin gör, inklusive alla in- och utvärden.
- Programvariabler och konstanter, och hur de används i applikationen.
- Den allmänna programstrukturen. För en diskbaserad applikation kan detta vara en beskrivning av programmets enskilda moduler och bibliotek, medan det för en webbapplikation kan beskriva vilka sidor som använder vilka filer.
2. Bestäm hur mycket av dokumentationen som ska ingå i programkoden och hur mycket som ska hållas åtskilda. Ju mer teknisk dokumentation som redan har utvecklats inom programmets källkod, desto lättare blir det att uppdatera och underhålla den tillsammans med koden, samt att dokumentera olika versioner av den ursprungliga applikationen. Dokumentation inom källkoden bör åtminstone förklara syftet med funktioner, subrutiner, variabler och konstanter.
3. Välj rätt dokumentationsverktyg. Till viss del bestäms detta av språket som koden är skriven på (som C++, C#, Visual Basic, Java eller PHP), eftersom specifika verktyg finns för dessa och andra språk. I andra fall avgör vilken typ av dokumentation som krävs vilket verktyg som ska användas.
Metod 2 av 2: Skriva mjukvarudokumentation för slutanvändare
1. Bestäm affärsskälen för din dokumentation. Även om det funktionella skälet för att dokumentera programvara är att hjälpa användare att förstå hur man använder applikationen, finns det andra skäl som att hjälpa till med att marknadsföra programvaran, förbättra företagets image och, framför allt, minska kostnaderna för teknisk support. I vissa fall är dokumentationen nödvändig för att uppfylla vissa föreskrifter eller andra lagkrav.
- Programvarudokumentation bör dock inte på något sätt ersätta dålig gränssnittsdesign. Om en applikation kräver sidor med dokumentation som vägledning, är det bättre att ändra skärmdesignen till något mer intuitivt.
2. Förstå den publik du skriver dokumentationen för. I de flesta fall har programanvändare liten kunskap om datorer utöver de uppgifter de kan utföra med de applikationer de använder. Det finns flera sätt att avgöra vad de behöver och hur din dokumentation kan tillgodose dem.
3. Bestäm rätt format för dokumentationen. Programvarudokumentationen kan struktureras i 1 av 2 format: manualen och användarmanualen. Ibland är en kombination av båda formaten den bästa metoden.
4. Bestäm vilken form dokumentationen ska ha. Programvarudokumentation kan ta många former: manualer, PDF-dokument, hjälpfiler eller onlinehjälp. Varje formulär är utformat för att visa användaren användningen av var och en av funktionerna i programmet, oavsett om det är i form av en genomgång eller handledning; när det gäller hjälpfiler och onlinehjälp kan detta vara såväl text som demonstrationsvideor samt bilder.
5. Välj ett lämpligt dokumentationsverktyg. Tryckta eller PDF-manualer kan skrivas med hjälp av ett ordbehandlingsprogram som Word, eller en avancerad textredigerare som FrameMaker, beroende på deras längd och komplexitet. Hjälpfiler kan skrivas med ett speciellt författarverktyg som RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix eller HelpServer.
Tips
- Texten ska vara organiserad så att den är lätt att läsa, med bilder så nära den text som den refererar till som möjligt. Dela upp dokumentationen logiskt i stycken, avsnitt och ämnen. Varje stycke eller ämne måste förklara en enskild fråga, vare sig det är en enskild programfunktion eller en uppgift. Relaterade problem kan förklaras, där så är lämpligt, med hjälp av "Se även"-listor eller hyperlänkar enligt ovan.
- Vilket som helst av dokumentationsverktygen som listas ovan kan kompletteras med ett skärmdumpsprogram, till exempel Snagit, om dokumentationen kräver några skärmdumpar. Som med annan dokumentation bör skärmdumpar inkluderas för att förklara hur programvaran fungerar, inte för att förvirra användaren.
- Tonen är mycket viktig, särskilt när du skriver programvarudokumentation för slutanvändare. Adressera användare i den andra personen ("du") istället för den tredje personen ("användaren").
Förnödenheter
- Programvarudokumentation/hjälpfilverktyg
- Skärmdumpsverktyg
"Skriva dokumentation för programvara"
Оцените, пожалуйста статью
