Gera programinės įrangos dokumentacija, nesvarbu, ar tai programuotojų ir bandytojų specifikacijų dokumentacija, techniniai vidaus vartotojų dokumentai, ar vadovai ir pagalbos failai galutiniams vartotojams, padės vartotojams suprasti programinės įrangos funkcijas ir funkcijas. Gera dokumentacija yra specifinė, aiški ir svarbi dokumentacija, kurioje pateikiama visa vartotojui reikalinga informacija. Šis straipsnis padės jums parašyti programinės įrangos dokumentus techniniams vartotojams ir galutiniams vartotojams.
Žingsnis
1 iš 2 metodas: programinės įrangos dokumentacijos rašymas techniniams vartotojams
Žingsnis 1. Žinokite, kokią informaciją įtraukti
Specifikacijų dokumentas naudojamas kaip informacinis vadovas sąsajų kūrėjams, programuotojams, kurie rašo kodą, ir bandytojams, kurie tikrina programinės įrangos veikimą. Informacija, kurią reikia įtraukti, priklausys nuo kuriamos programos, tačiau gali apimti:
- Svarbūs programos failai, pvz., Kūrimo komandos sukurti failai, duomenų bazės, prieinamos programos veikimo metu, ir trečiųjų šalių programos.
- Funkcijos ir paprogramės, įskaitant funkcijos/paprogramės naudojimo paaiškinimus, įvesties ir išvesties reikšmes.
- Programos kintamieji ir konstantos bei kaip jie naudojami.
- Bendra programos struktūra. Disko programoms gali tekti aprašyti kiekvieną modulį ir biblioteką. Arba, jei rašote žiniatinklio programos vadovą, gali tekti paaiškinti, kuriuos failus naudoja kiekvienas puslapis.
Žingsnis 2. Nuspręskite, kokio lygio dokumentai turėtų būti pateikti ir atskirti nuo programos kodo
Kuo daugiau techninės dokumentacijos bus įtraukta į programos kodą, tuo lengviau bus ją atnaujinti ir prižiūrėti, taip pat paaiškinti skirtingas programos versijas. Programos kodo dokumentuose turėtų būti bent jau funkcijų, paprogramių, kintamųjų ir konstantų naudojimas.
- Jei jūsų šaltinio kodas yra ilgas, galite parašyti dokumentus į pagalbos failą, kurį galima indeksuoti arba ieškoti tam tikrais raktiniais žodžiais. Atskiri dokumentacijos failai yra naudingi, jei programos logika yra padalinta į kelis puslapius ir apima palaikymo failus, pvz., Žiniatinklio programą.
- Kai kurios programavimo kalbos (pvz., „Java“, „Visual Basic. NET“ar „C#“) turi savo kodo dokumentacijos standartus. Tokiais atvejais vadovaukitės standartiniais dokumentais, kurie turi būti įtraukti į šaltinio kodą.
Žingsnis 3. Pasirinkite tinkamą dokumentacijos įrankį
Kai kuriais atvejais dokumentacijos įrankis nustatomas pagal naudojamą programavimo kalbą. Kalbos C ++, C#, Visual Basic, Java, PHP ir kitos turi savo dokumentacijos įrankius. Tačiau jei ne, naudojamos priemonės priklausys nuo reikalingos dokumentacijos.
- Teksto redagavimo priemonė, pvz., „Microsoft Word“, tinka dokumentų teksto failams kurti, jei dokumentacija yra glausta ir paprasta. Norėdami sukurti ilgą dokumentaciją su sudėtingu tekstu, dauguma techninių autorių pasirenka specializuotą dokumentacijos įrankį, pvz., „Adobe FrameMaker“.
- Pagalbos failus, skirtus šaltinio kodui dokumentuoti, galima sukurti naudojant palaikymo failų generatoriaus programą, pvz., „RoboHelp“, „Help and Manual“, „Doc-To-Help“, „MadCap Flare“arba „HelpLogix“.
2 metodas iš 2: programinės įrangos dokumentacijos rašymas galutiniams vartotojams
Žingsnis 1. Žinokite verslo priežastis, kuriomis grindžiamas vadovo kūrimas
Nors pagrindinė programinės įrangos dokumentacijos priežastis yra padėti vartotojams suprasti, kaip naudotis programa, yra keletas kitų priežasčių, dėl kurių gali būti kuriama dokumentacija, pavyzdžiui, padėti rinkodaros skyriui parduoti programą, pagerinti įmonės įvaizdį ir sumažinti techninę pagalbą. išlaidų. Kai kuriais atvejais dokumentai reikalingi, kad atitiktų reglamentus ar kitus teisinius reikalavimus.
Tačiau dokumentai nėra geras sąsajos pakaitalas. Jei programai reikia daug dokumentų, ji turėtų būti sukurta taip, kad būtų intuityvesnė
Žingsnis 2. Žinokite dokumentacijos tikslinę auditoriją
Paprastai programinės įrangos vartotojai turi ribotas žinias apie kompiuterį, išskyrus jų naudojamas programas. Yra keli būdai, kaip patenkinti jų dokumentus:
- Atkreipkite dėmesį į programinės įrangos vartotojo pavadinimą. Pavyzdžiui, sistemos administratorius paprastai supranta įvairias kompiuterines programas, o sekretorius žino tik tas programas, kurias naudoja duomenims įvesti.
- Atkreipkite dėmesį į programinės įrangos vartotojus. Nors jų pareigos paprastai yra suderinamos su atliekamomis užduotimis, šios pareigos gali būti skirtingos, atsižvelgiant į verslo vietą. Apklausdami potencialius vartotojus, galite sužinoti, ar teisingai vertinate jų pareigas.
- Atkreipkite dėmesį į esamus dokumentus. Programinės įrangos funkcionalumo dokumentacija ir specifikacijos gali parodyti, ką vartotojai turi žinoti, kad galėtų jais naudotis. Tačiau atminkite, kad vartotojams gali būti neįdomu žinoti programos „vidines puses“.
- Žinokite, ko reikia užduočiai atlikti ir ko reikia, kad galėtumėte ją atlikti.
Žingsnis 3. Nustatykite tinkamą dokumentų formatą
Programinės įrangos dokumentacija gali būti sudaryta 1 arba 2 formatais, būtent žinynai ir vadovai. Kartais abiejų formatų derinimas yra geras sprendimas.
- Pamatiniai formatai naudojami apibūdinti visas programinės įrangos funkcijas, pvz., Mygtukus, skirtukus, laukus ir dialogo langus bei jų veikimą. Kai kurie pagalbos failai yra parašyti šiuo formatu, ypač tie, kurie yra jautrūs kontekstui. Kai tam tikrame ekrane vartotojas spustelės Pagalba, vartotojas gaus atitinkamą temą.
- Rankinis formatas naudojamas paaiškinti, kaip ką nors padaryti naudojant programinę įrangą. Instrukcijos paprastai yra spausdintos arba PDF formato, nors kai kuriuose pagalbos puslapiuose taip pat yra nurodymų, kaip atlikti tam tikrus veiksmus. (Paprastai rankiniai formatai nėra jautrūs kontekstui, tačiau gali būti susieti su kontekstui jautriomis temomis). Vadovai paprastai pateikiami vadovo pavidalu, aprašant aprašomą užduočių santrauką ir žingsnis po žingsnio suformatuotą vadovą.
Žingsnis 4. Nuspręskite dėl dokumentacijos tipo
Programinės įrangos dokumentai vartotojams gali būti supakuoti vienu ar daugiau iš šių formatų: spausdinti vadovai, PDF failai, pagalbos failai arba internetinė pagalba. Kiekviena dokumentacijos rūšis skirta parodyti, kaip naudotis programinės įrangos funkcijomis, nesvarbu, ar tai vadovas, ar pamoka. Internetiniai dokumentai ir pagalbos puslapiai taip pat gali apimti demonstracinius vaizdo įrašus, tekstą ir statinius vaizdus.
Interneto pagalbos ir palaikymo failai turėtų būti indeksuojami ir ieškomi naudojant raktinius žodžius, kad vartotojai galėtų greitai rasti reikiamą informaciją. Nors pagalbos failų generatoriaus programa gali automatiškai sukurti indeksą, vis tiek rekomenduojama rodyklę sukurti rankiniu būdu, naudojant dažniausiai ieškomus raktinius žodžius
Žingsnis 5. Pasirinkite tinkamą dokumentacijos įrankį
Atsižvelgiant į failo ilgį ir sudėtingumą, spausdintus vadovus ar PDF failus galima sukurti naudojant teksto apdorojimo programą, pvz., „Word“, arba patobulintą teksto redaktorių, pvz., „FrameMaker“. Pagalbos failus galima parašyti naudojant pagalbos failų kūrimo programą, pvz., „RoboHelp“, „Help and Manual“, „Doc-To-Help“, „Flare“, „HelpLogix“arba „HelpServer“.
Patarimai
- Programos dokumentacijos tekstas turėtų būti sudarytas taip, kad jį būtų lengva perskaityti. Padėkite vaizdą kuo arčiau tinkamo teksto. Logiškai suskirstykite dokumentus pagal skyrius ir temas. Kiekvienoje skiltyje ar temoje turėtų būti aprašyta konkreti problema, tiek užduotis, tiek programos ypatybės. Susijusius klausimus galima paaiškinti nuorodomis ar nuorodų sąrašais.
- Kiekvieną šiame straipsnyje aprašytą dokumentacijos įrankį galima papildyti ekrano kopijų kūrimo programa, pvz., „SnagIt“, jei jūsų dokumentacijai reikia kelių ekrano kopijų. Kaip ir bet kuri kita dokumentacija, taip pat turėtumėte įtraukti ekrano kopijas, kurios padėtų paaiškinti, kaip programa veikia, o ne „vilioti“naudotoją.
- Labai svarbu atkreipti dėmesį į stilių, ypač jei rašote programinės įrangos dokumentus galutiniams vartotojams. Kreipkitės į vartotojus su įvardžiu „jūs“, o ne „vartotojas“.
