Laba programmatūras dokumentācija, neatkarīgi no tā, vai tā ir specifikācijas dokumentācija programmētājiem un testētājiem, tehniskie dokumenti iekšējiem lietotājiem vai rokasgrāmatas un palīdzības faili gala lietotājiem, palīdzēs lietotājiem izprast programmatūras funkcijas un funkcijas. Laba dokumentācija ir specifiska, skaidra un atbilstoša dokumentācija ar visu lietotājam nepieciešamo informāciju. Šis raksts jums palīdzēs rakstīt programmatūras dokumentāciju tehniskajiem lietotājiem un gala lietotājiem.
Solis
1. metode no 2: programmatūras dokumentācijas rakstīšana tehniskajiem lietotājiem
1. solis. Ziniet, kādu informāciju iekļaut
Specifikācijas dokuments tiek izmantots kā atsauces rokasgrāmata saskarnes dizaineriem, programmētājiem, kuri raksta kodu, un testētājiem, kuri pārbauda programmatūras veiktspēju. Informācija, kas jāiekļauj, būs atkarīga no izveidotās programmas, bet var ietvert šādu informāciju:
- Svarīgi lietojumprogrammas faili, piemēram, izstrādes komandas izveidotie faili, programmas darbības laikā piekļūtās datu bāzes un trešo pušu lietojumprogrammas.
- Funkcijas un apakšprogrammas, ieskaitot skaidrojumu par funkcijas/apakšprogrammas izmantošanu, ievades un izvades vērtībām.
- Programmas mainīgie un konstantes un to izmantošana.
- Programmas vispārējā struktūra. Uz disku balstītām programmām, iespējams, būs jāapraksta katrs modulis un bibliotēka. Vai arī, ja jūs rakstāt rokasgrāmatu tīmekļa programmai, jums, iespējams, būs jāpaskaidro, kurus failus katra lapa izmanto.
2. solis. Izlemiet, kādam dokumentācijas līmenim jābūt klāt un atdalāmam no programmas koda
Jo tehniskāka dokumentācija ir iekļauta programmas kodā, jo vieglāk būs to atjaunināt un uzturēt, kā arī izskaidrot dažādas programmas versijas. Programmas koda dokumentācijā jāiekļauj vismaz funkciju, apakšprogrammu, mainīgo un konstantu izmantošana.
- Ja avota kods ir garš, varat ierakstīt dokumentāciju palīdzības failā, kuru pēc tam var indeksēt vai meklēt, izmantojot noteiktus atslēgvārdus. Atsevišķi dokumentācijas faili ir noderīgi, ja programmas loģika ir sadalīta vairākās lapās un ietver atbalsta failus, piemēram, tīmekļa lietojumprogrammu.
- Dažām programmēšanas valodām (piemēram, Java, Visual Basic. NET vai C#) ir savi koda dokumentācijas standarti. Šādos gadījumos ievērojiet standarta dokumentāciju, kas jāiekļauj avota kodā.
3. solis. Izvēlieties atbilstošo dokumentācijas rīku
Dažos gadījumos dokumentācijas rīku nosaka izmantotā programmēšanas valoda. Valodām C ++, C#, Visual Basic, Java, PHP un citām ir savi dokumentācijas rīki. Tomēr, ja nē, izmantotie rīki būs atkarīgi no nepieciešamās dokumentācijas.
- Teksta procesors, piemēram, Microsoft Word, ir piemērots dokumentu teksta failu izveidei, ja vien dokumentācija ir kodolīga un vienkārša. Lai izveidotu garu dokumentāciju ar sarežģītu tekstu, lielākā daļa tehnisko autoru izvēlas specializētu dokumentācijas rīku, piemēram, Adobe FrameMaker.
- Palīdzības failus avota koda dokumentēšanai var izveidot, izmantojot atbalsta failu ģeneratora programmu, piemēram, RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare vai HelpLogix.
2. metode no 2: Programmatūras dokumentācijas rakstīšana galalietotājiem
1. solis. Ziniet rokasgrāmatas izveides pamatā esošos biznesa iemeslus
Lai gan programmatūras dokumentācijas galvenais iemesls ir palīdzēt lietotājiem saprast, kā lietot lietojumprogrammu, ir vairāki citi iemesli, kas var būt pamatā dokumentācijas izveidei, piemēram, palīdzība mārketinga nodaļai pārdot lietojumprogrammu, uzlabot uzņēmuma tēlu un samazināt tehnisko atbalstu. izmaksas. Dažos gadījumos dokumentācija ir nepieciešama, lai atbilstu noteikumiem vai citām juridiskām prasībām.
Tomēr dokumentācija nav labs interfeisa aizstājējs. Ja lietojumprogrammas darbībai ir nepieciešams daudz dokumentācijas, tā jāveido tā, lai tā būtu intuitīvāka
2. Ziniet dokumentācijas mērķauditoriju
Parasti programmatūras lietotājiem ir ierobežotas zināšanas par datoru, izņemot lietotās lietojumprogrammas. Ir vairāki veidi, kā apmierināt viņu dokumentācijas vajadzības:
- Pievērsiet uzmanību programmatūras lietotāja nosaukumam. Piemēram, sistēmas administrators parasti saprot dažādas datoru lietojumprogrammas, savukārt sekretārs zina tikai tās lietojumprogrammas, kuras viņš izmanto datu ievadīšanai.
- Pievērsiet uzmanību programmatūras lietotājiem. Lai gan viņu amati parasti ir saderīgi ar veiktajiem uzdevumiem, šiem amatiem var būt atšķirīga slodze atkarībā no uzņēmējdarbības vietas. Aptaujājot potenciālos lietotājus, jūs varat uzzināt, vai viņu amata nosaukuma novērtējums ir pareizs.
- Pievērsiet uzmanību esošajai dokumentācijai. Programmatūras funkcionalitātes dokumentācija un specifikācijas var parādīt, kas lietotājiem jāzina, lai tās varētu izmantot. Tomēr paturiet prātā, ka lietotāji, iespējams, nav ieinteresēti uzzināt programmas iekšējās īpašības.
- Ziniet, kas nepieciešams, lai pabeigtu uzdevumu, un kas nepieciešams, pirms varat to pabeigt.
3. solis. Nosakiet atbilstošo dokumentācijas formātu
Programmatūras dokumentāciju var sakārtot 1 vai 2 formātos, proti, uzziņu grāmatas un rokasgrāmatas. Dažreiz abu formātu apvienošana ir labs risinājums.
- Atsauces formātus izmanto, lai aprakstītu visas programmatūras funkcijas, piemēram, pogas, cilnes, laukus un dialoglodziņus un to darbību. Daži palīdzības faili ir rakstīti šajā formātā, īpaši tie, kas ir jutīgi pret kontekstu. Kad lietotājs noteiktā ekrānā noklikšķina uz Palīdzība, lietotājs saņems attiecīgo tēmu.
- Manuālais formāts tiek izmantots, lai izskaidrotu, kā kaut ko darīt ar programmatūru. Rokasgrāmatas parasti ir drukātā vai PDF formātā, lai gan dažās palīdzības lapās ir arī norādījumi par noteiktu darbību veikšanu. (Parasti manuālie formāti nav konteksta jutīgi, bet var būt saistīti ar konteksta jutīgām tēmām). Rokasgrāmatas parasti ir ceļveža veidā, aprakstā veicot veicamo uzdevumu kopsavilkumu un soļos formatējot rokasgrāmatu.
4. solis. Izlemiet par dokumentācijas veidu
Programmatūras dokumentācija lietotājiem var būt iepakota vienā vai vairākos šādos formātos: drukātas rokasgrāmatas, PDF faili, palīdzības faili vai tiešsaistes palīdzība. Katrs dokumentācijas veids ir izstrādāts, lai parādītu, kā izmantot programmatūras funkcijas neatkarīgi no tā, vai tas ir ceļvedis vai apmācība. Tiešsaistes dokumentācijā un palīdzības lapās var būt arī demonstrācijas video, teksts un statiski attēli.
Tiešsaistes palīdzības un atbalsta failiem jābūt indeksētiem un meklējamiem, izmantojot atslēgvārdus, lai lietotāji varētu ātri atrast nepieciešamo informāciju. Lai gan palīdzības failu ģeneratora lietojumprogramma var automātiski izveidot indeksu, tomēr ieteicams rādītāju izveidot manuāli, izmantojot bieži meklētos atslēgvārdus
5. solis. Izvēlieties atbilstošo dokumentācijas rīku
Drukātas rokasgrāmatas vai PDF failus var izveidot, izmantojot tekstapstrādes programmu, piemēram, Word, vai uzlabotu teksta redaktoru, piemēram, FrameMaker, atkarībā no faila garuma un sarežģītības. Palīdzības failus var rakstīt ar palīdzības failu izveides programmu, piemēram, RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix vai HelpServer.
Padomi
- Programmas dokumentācijas tekstam jābūt strukturētam tā, lai tas būtu viegli lasāms. Novietojiet attēlu pēc iespējas tuvāk atbilstošajam tekstam. Loģiski sadaliet dokumentāciju pēc sadaļām un tēmām. Katrā sadaļā vai tēmā jāapraksta konkrēta problēma - gan uzdevuma, gan programmas iezīmes. Saistītās problēmas var izskaidrot ar saitēm vai atsauču sarakstiem.
- Katru no šajā rakstā aprakstītajiem dokumentācijas rīkiem var papildināt ar ekrānuzņēmumu veidotāja programmu, piemēram, SnagIt, ja dokumentācijai nepieciešami vairāki ekrānuzņēmumi. Tāpat kā jebkura cita dokumentācija, jums ir jāiekļauj arī ekrānuzņēmumi, lai palīdzētu izskaidrot lietotnes darbību, nevis “pievilināt” lietotāju.
- Pievērst uzmanību stilam ir ļoti svarīgi, it īpaši, ja rakstāt programmatūras dokumentāciju galalietotājiem. Uzrunājiet lietotājus ar vietniekvārdu “jūs”, nevis “lietotājs”.
