Hea tarkvara dokumentatsioon, olgu see siis programmeerijate ja testijate spetsifikatsioonidokument, sisekasutuse tehnilised dokumendid või lõppkasutajate käsiraamatud ja abifailid, aitab kasutajatel mõista tarkvara funktsioone ja funktsioone. Hea dokumentatsioon on konkreetne, selge ja asjakohane dokumentatsioon, mis sisaldab kogu kasutajale vajalikku teavet. See artikkel juhendab teid tehniliste ja lõppkasutajate jaoks tarkvara dokumentatsiooni kirjutamiseks.
Samm
Meetod 1 /2: Tarkvara dokumentatsiooni kirjutamine tehnilistele kasutajatele
Samm 1. Tea, millist teavet lisada
Spetsifikatsioonidokumenti kasutatakse viitejuhendina liideste kujundajatele, programmeerijatele, kes kirjutavad koodi, ja testijatele, kes kontrollivad tarkvara jõudlust. Lisatav teave sõltub loodavast programmist, kuid võib sisaldada järgmist.
- Rakenduse olulised failid, näiteks arendusmeeskonna loodud failid, programmi töötamise ajal juurdepääsetavad andmebaasid ja kolmanda osapoole rakendused.
- Funktsioonid ja alamprogrammid, sealhulgas selgitus funktsiooni/alamprogrammi kasutamise, sisend- ja väljundväärtuste kohta.
- Programmi muutujad ja konstandid ning nende kasutamine.
- Programmi üldine struktuur. Draivipõhiste programmide puhul peate võib-olla kirjeldama iga moodulit ja kogu. Või kui kirjutate veebipõhise programmi käsiraamatut, peate võib-olla selgitama, milliseid faile iga leht kasutab.
Samm 2. Otsustage, milline dokumentatsiooni tase peaks olema ja programmi koodist eraldatav
Mida tehnilisem dokumentatsioon on programmi koodis, seda lihtsam on seda värskendada ja hooldada, samuti selgitada programmi erinevaid versioone. Programmi koodi dokumentatsioon peaks vähemalt sisaldama funktsioonide, alamprogrammide, muutujate ja konstandite kasutamist.
- Kui teie lähtekood on pikk, saate kirjutada dokumentatsiooni abifaili, mida saab seejärel teatud märksõnadega indekseerida või otsida. Eraldi dokumentatsioonifailid on kasulikud, kui programmi loogika on jagatud mitmele lehele ja see sisaldab tugifaile, näiteks veebirakendust.
- Mõnel programmeerimiskeelel (nt Java, Visual Basic. NET või C#) on oma kooddokumentatsiooni standardid. Sellistel juhtudel järgige standarddokumentatsiooni, mis tuleb lähtekoodi lisada.
Samm 3. Valige sobiv dokumentatsiooni tööriist
Mõnel juhul määrab dokumentatsioonivahendi kasutatav programmeerimiskeel. Keeltel C ++, C#, Visual Basic, Java, PHP ja teistel on oma dokumenteerimistööriistad. Kui ei, siis sõltuvad kasutatavad tööriistad nõutavast dokumentatsioonist.
- Dokumendi tekstifailide loomiseks sobib tekstitöötlusprogramm, näiteks Microsoft Word, kui dokumentatsioon on lühike ja lihtne. Keerulise tekstiga pika dokumentatsiooni loomiseks valib enamik tehnilisi kirjutajaid spetsiaalse dokumentatsiooni tööriista, näiteks Adobe FrameMaker.
- Lähtekoodi dokumenteerimise abifaile saab luua tugifailide generaatoriprogrammiga, näiteks RoboHelp, Help ja Manual, Doc-To-Help, MadCap Flare või HelpLogix.
Meetod 2/2: Tarkvara dokumentatsiooni kirjutamine lõppkasutajatele
Samm 1. Teadke käsiraamatu koostamise ärilistel põhjustel
Kuigi tarkvara dokumentatsiooni peamine põhjus on aidata kasutajatel rakendust kasutada, on dokumentatsiooni loomise aluseks mitmeid muid põhjuseid, näiteks turundusosakonna abistamine rakenduse müümisel, ettevõtte maine parandamine ja tehnilise toe vähendamine. kulusid. Mõnel juhul on määruste või muude juriidiliste nõuete järgimiseks vajalik dokumentatsioon.
Siiski ei asenda dokumentatsioon liidest hästi. Kui rakenduse kasutamiseks on vaja palju dokumente, peaks see olema intuitiivsem
Samm 2. Tunne dokumentatsiooni sihtrühma
Üldiselt on tarkvara kasutajatel arvutiteadmised piiratud nende poolt kasutatavate rakendustega. Nende dokumentide vajaduste rahuldamiseks on mitu võimalust:
- Pöörake tähelepanu tarkvara kasutaja pealkirjale. Näiteks süsteemiadministraator mõistab üldiselt erinevaid arvutirakendusi, sekretär aga teab ainult neid rakendusi, mida ta andmete sisestamiseks kasutab.
- Pöörake tähelepanu tarkvara kasutajatele. Kuigi nende ametikohad ühilduvad üldjuhul täidetavate ülesannetega, võivad need ametikohad olla erineva töökoormusega, sõltuvalt tegevuskohast. Potentsiaalseid kasutajaid küsitledes saate teada, kas teie hinnang nende ametinimetusele on õige.
- Pöörake tähelepanu olemasolevale dokumentatsioonile. Tarkvara funktsionaalsuse dokumentatsioon ja spetsifikatsioonid võivad näidata, mida kasutajad peavad nende kasutamiseks teadma. Kuid pidage meeles, et kasutajad ei pruugi olla huvitatud programmi sisemuste teadmisest.
- Tea, mida on vaja ülesande täitmiseks ja mis kulub enne selle täitmist.
Samm 3. Määrake dokumentide jaoks sobiv vorming
Tarkvara dokumentatsiooni saab korraldada 1 või 2 vormingus, nimelt teatmeteoseid ja käsiraamatuid. Mõnikord on nende kahe vormingu kombineerimine hea lahendus.
- Viitavorminguid kasutatakse kõigi tarkvarafunktsioonide, näiteks nuppude, vahelehtede, väljade ja dialoogibokside ning nende toimimise kirjeldamiseks. Mõned abifailid on kirjutatud selles vormingus, eriti need, mis on kontekstitundlikud. Kui kasutaja klõpsab teatud ekraanil Abi, saab kasutaja vastava teema.
- Käsitsi vormingus selgitatakse, kuidas tarkvaraga midagi teha. Käsiraamatud on tavaliselt trükitud või PDF -vormingus, kuigi mõned abilehed sisaldavad ka juhiseid teatud toimingute tegemiseks. (Üldiselt ei ole manuaalsed vormingud kontekstitundlikud, kuid võivad olla lingitud kontekstitundlikest teemadest). Käsiraamatud on üldjuhul juhendi kujul, koos kirjelduses täidetavate ülesannete kokkuvõttega ja samm -sammult vormistatud juhendiga.
Samm 4. Otsustage dokumentatsiooni tüüp
Kasutajate tarkvara dokumentatsioon võib olla pakitud ühte või mitmesse järgmistest vormingutest: trükitud juhendid, PDF -failid, abifailid või veebiabi. Igat tüüpi dokumentatsioon on loodud näitamaks teile, kuidas tarkvara funktsioone kasutada, olgu see siis juhend või õpetus. Veebidokumentatsioon ja abilehed võivad sisaldada ka näidisvideoid, teksti ja staatilisi pilte.
Interneti -abi ja tugifailid tuleks indekseerida ja otsida märksõnade abil, et kasutajad leiaksid vajaliku teabe kiiresti. Kuigi abifailide generaatori rakendus suudab indeksi luua automaatselt, on siiski soovitatav indeks luua käsitsi, kasutades sageli otsitud märksõnu
Samm 5. Valige sobiv dokumentatsiooni tööriist
Sõltuvalt faili pikkusest ja keerukusest saab trükitud käsiraamatuid või PDF -faile luua tekstitöötlusprogrammiga, nagu Word või täiustatud tekstiredaktor, näiteks FrameMaker. Abifaile saab kirjutada abifailide loomise programmiga, näiteks RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix või HelpServer.
Näpunäiteid
- Programmi dokumentatsiooni tekst peaks olema struktureeritud nii, et seda oleks lihtne lugeda. Asetage pilt sobivale tekstile võimalikult lähedale. Jagage dokumentatsioon jaotiste ja teemade kaupa loogiliselt. Iga jaotis või teema peaks kirjeldama konkreetset probleemi, nii ülesannet kui ka programmi funktsioone. Seotud probleeme saab selgitada linkide või viitete loenditega.
- Kõiki käesolevas artiklis kirjeldatud dokumenteerimistööriistu saab täiendada ekraanipiltide tegemise programmiga, näiteks SnagIt, kui teie dokumentatsioon nõuab mitut ekraanipilti. Nagu iga muu dokumentatsioon, peaksite ka rakenduse toimimise selgitamiseks lisama ekraanipildid, mitte kasutaja "meelitamiseks".
- Stiilile tähelepanu pööramine on väga oluline, eriti kui kirjutate tarkvara dokumentatsiooni lõppkasutajatele. Pöörduge kasutajate poole asesõnaga „teie”, mitte „kasutaja”.
