Hea tarkvara dokumentatsioon, olgu siis tehniline dokument programmeerijatele ja testijatele, tehniline dokument sisekasutajatele või tarkvara juhendid ja abifailid lõppkasutajatele, aitab tarkvaraga töötaval inimesel mõista selle funktsioone ja funktsioone. Hea tarkvara dokumentatsioon on konkreetne, lühike ja asjakohane, pakkudes kogu tarkvara kasutavale inimesele olulist teavet. Järgmised juhised tehnilistele kasutajatele ja lõppkasutajatele mõeldud tarkvaradokumentatsiooni kirjutamise kohta.
1
Määrake, millist teavet tuleb lisada. Tarkvara spetsifikatsioonidokumendid on kasutusjuhendid kasutajaliidese kujundajatele, programmeerijatele, kes kirjutavad koodi, ja testijatele, kes kontrollivad, kas tarkvara töötab ettenähtud viisil. Täpne teave sõltub kõnealusest programmist, kuid võib sisaldada järgmist: rakenduse võtmefailid. See võib hõlmata arendusmeeskonna loodud faile, programmi töö ajal juurde pääsetud andmebaase ja kolmanda osapoole utiliiti. Funktsioonid ja alamprogrammid. See sisaldab selgitust selle kohta, mida iga funktsioon või alamprogramm teeb, sealhulgas selle sisendväärtuste ja väljundväärtuste vahemikku.Programmi muutujad ja konstandid ning kuidas neid rakenduses kasutatakse.Programmi üldine struktuur. Plaadipõhise rakenduse puhul võib see tähendada programmi üksikute moodulite ja teekide kirjeldamist, veebirakenduse puhul aga kirjeldamist, millised lehed milliseid faile kasutavad.
2
Otsustage, kui suur osa dokumentatsioonist peaks olema programmikoodi sees ja kui palju sellest eraldi. Mida rohkem tehnilist dokumentatsiooni programmi lähtekoodis alguses välja töötatakse, seda lihtsam on seda koos koodiga värskendada ja hooldada, samuti dokumenteerida algse rakenduse erinevaid versioone. Lähtekoodi dokumentatsioon peab vähemalt selgitama funktsioonide, alamprogrammide, muutujate ja konstantide eesmärki. Kui lähtekood on eriti pikk, saab selle dokumenteerida abifailina, mida saab indekseerida või otsida. märksõnadega. See on eriline eelis rakenduste puhul, mille programmiloogika on killustatud paljudel lehtedel ja sisaldab mitmeid täiendavaid faile, nagu teatud veebirakenduste puhul. Mõned programmeerimiskeeled, nagu Java ja .NET Framework (Visual Basic.NET, C # ), neil on koodi dokumenteerimiseks oma standardid. Sellistel juhtudel järgige standardeid selle kohta, kui suur osa dokumentatsioonist peaks lähtekoodiga kaasas olema.
3
Valige sobiv dokumentatsioonitööriist. Mingil määral määrab selle keel, milles kood on kirjutatud, olgu selleks C++, C#, Visual Basic, Java või PHP, kuna nende ja teiste keelte jaoks on olemas spetsiaalsed tööriistad. Muudel juhtudel määrab kasutatava tööriista vajaliku dokumentatsiooni tüüp. Microsoft Wordi tekstitöötlusprogrammid on piisavad dokumentatsiooni eraldi tekstifailide loomiseks, kui dokumentatsioon on üsna lühike ja lihtne. Pikkade ja keeruliste tekstifailide puhul eelistavad paljud tehnilised autorid dokumentatsioonitööriista, nagu Adobe FrameMaker. Lähtekoodi dokumenteerimiseks mõeldud abifaile saab luua mis tahes abitööriistaga, nagu RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare. või HelpLogix.
4
Tehke kindlaks oma dokumentatsiooni ärilised põhjused. Kuigi tarkvara dokumenteerimise funktsionaalne põhjus on aidata kasutajatel mõista, kuidas rakendust kasutada, on ka muid põhjuseid, näiteks abistamine tarkvara turundamisel, ettevõtte maine parandamine ja eelkõige tehnilise toe kulude vähendamine. Mõnel juhul on dokumentatsioon vajalik teatud eeskirjade või muude juriidiliste nõuete täitmiseks. Tarkvara dokumentatsioon ei tohi aga mingil juhul asendada kehva liidese disaini. Kui rakenduse ekraan vajab selle selgitamiseks hulgaliselt dokumente, on parem muuta ekraani kujundus midagi intuitiivsemat.
5
Mõistke publikut, kellele dokumentatsiooni kirjutate. Enamasti on tarkvarakasutajatel vähe teadmisi arvutitest väljaspool nende kasutatavaid rakendusi. Nende vajaduste rahuldamiseks oma dokumentatsiooni abil on mitu võimalust. Vaadake oma potentsiaalsete kasutajate ametinimetusi. Süsteemiadministraator on tõenäoliselt paljude tarkvararakenduste ekspert, samas kui andmesisestusametnik tunneb tõenäolisemalt ainult rakendust, mida ta praegu andmete sisestamiseks kasutab. Vaadake kasutajaid endid. Kuigi ametinimetused näitavad üldiselt, mida inimesed teevad, võib teatud ametinimetuste kasutamine antud organisatsioonis oluliselt erineda. Intervjueerides potentsiaalseid kasutajaid, saate aimu, kas teie muljed nende ametinimetusest on õiged või mitte. Vaadake olemasolevat dokumentatsiooni. Varasemate tarkvaraversioonide dokumentatsioon ja funktsionaalsed spetsifikatsioonid näitavad, mida kasutaja peab programmi kasutamiseks teadma. Pidage siiski meeles, et lõppkasutajaid ei huvita niivõrd see, kuidas programm töötab, kuivõrd see, mida see nende heaks teha saab. Tehke kindlaks, millised ülesanded on töö tegemiseks vajalikud ja millised ülesanded tuleb teha enne, kui neid ülesandeid saab teha tehtud.
6
Tehke kindlaks dokumentatsiooni sobiv vorming (vormingud). Tarkvara dokumentatsiooni saab struktureerida ühes kahest vormingust: viitejuhend ja kasutusjuhend. Mõnikord on parim lahendus vormingute kombinatsioon. Viitejuhendi vorming on pühendatud tarkvararakenduse üksikute funktsioonide (nupp, vahekaart, väli ja dialoogiboks) ja nende toimimise selgitamisele. Paljud abifailid on kirjutatud selles vormingus, eriti kontekstitundlik spikker, mis kuvab asjakohase teema iga kord, kui kasutaja klõpsab konkreetsel ekraanil nuppu Spikker. Kasutusjuhendi vorming selgitab, kuidas tarkvara konkreetse ülesande täitmiseks kasutada. Kasutusjuhendid on sageli vormindatud trükitud juhendite või PDF-failidena, kuigi mõned spikrifailid sisaldavad teatud toimingute sooritamise teemasid. (Need abiteemad ei ole tavaliselt kontekstitundlikud, kuigi neile võib olla hüperlinke teemadelt.) Kasutusjuhendid on sageli õpetuste vormis, kus on sissejuhatuses tehtavate ülesannete kokkuvõte ja juhised nummerdatud sammudena. .
7
Otsustage, millises vormis dokumentatsioon peaks olema. Lõppkasutajatele mõeldud tarkvaradokumentatsioon võib esineda ühes või mitmes vormis: trükitud juhendid, PDF-dokumendid, abifailid või veebispikker. Iga vorm on loodud näitama kasutajale, kuidas kasutada iga programmi funktsiooni, olgu see siis läbivaatuse või õpetuse kujul; abifailide ja veebispikri puhul võib see hõlmata nii esitlusvideoid kui ka teksti ja graafikat. Abifailid ja veebispikker peaksid olema indekseeritud ja märksõnadega otsitavad, et kasutajad saaksid otsitava teabe kiiresti leida. Kuigi abifailide loomise tööriistad saavad indekseid automaatselt luua, on sageli parem register käsitsi luua, kasutades termineid, mida kasutajad tõenäoliselt otsivad.
8
Valige sobiv dokumentatsioonitööriist. Trükitud või PDF-vormingus kasutusjuhendeid saab sõltuvalt nende pikkusest ja keerukusest kirjutada tekstitöötlusprogrammiga (nt Word) või keeruka tekstiredaktoriga (nt FrameMaker). Abifaile saab kirjutada spikri loomise tööriistaga, nagu RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix või HelpServer.