Mahusay na dokumentasyon ng software, maging dokumentasyon ng pagtutukoy para sa mga programmer at tester, teknikal na dokumento para sa panloob na mga gumagamit, o mga manwal at tulong sa mga file para sa mga end user, ay makakatulong sa mga gumagamit na maunawaan ang mga tampok at pag-andar ng software. Ang mabuting dokumentasyon ay dokumentasyon na tukoy, malinaw, at nauugnay, kasama ang lahat ng impormasyong kinakailangan ng gumagamit. Gagabayan ka ng artikulong ito upang magsulat ng dokumentasyon ng software para sa mga teknikal na gumagamit at mga end user.
Hakbang
Paraan 1 ng 2: Pagsulat ng Dokumentasyon ng Software para sa Mga Teknikal na Gumagamit
Hakbang 1. Alamin kung anong impormasyon ang isasama
Ang dokumento ng pagtutukoy ay ginagamit bilang isang manwal ng sanggunian para sa mga tagadisenyo ng interface, programmer na nagsusulat ng code, at mga tester na nagpapatunay sa pagganap ng software. Ang impormasyon na kailangang isama ay nakasalalay sa programa na nilikha, ngunit maaaring isama ang mga sumusunod:
- Mahalagang mga file sa application, tulad ng mga file na nilikha ng koponan ng pag-unlad, na-access ang mga database habang tumatakbo ang programa, at mga application ng third-party.
- Mga pag-andar at subroutine, kabilang ang isang paliwanag sa paggamit ng mga halaga ng pag-andar / subroutine, input at output.
- Mga variable ng programa at pare-pareho, at kung paano ito ginagamit.
- Pangkalahatang istraktura ng programa. Para sa mga programang nakabatay sa pagmamaneho, maaaring kailanganin mong ilarawan ang bawat module at silid-aklatan. O, kung nagsusulat ka ng isang manwal para sa isang program na batay sa web, maaaring kailangan mong ipaliwanag kung aling mga file ang ginagamit ng bawat pahina.
Hakbang 2. Magpasya kung anong antas ng dokumentasyon ang dapat naroroon at mapaghihiwalay mula sa code ng programa
Ang mas maraming teknikal na dokumentasyon na kasama sa code ng programa, mas madali itong mai-update at mapanatili ito, pati na rin ipaliwanag ang iba't ibang mga bersyon ng programa. Sa isang minimum, ang dokumentasyon sa code ng programa ay dapat na may kasamang paggamit ng mga pagpapaandar, subroutine, variable, at pare-pareho.
- Kung mahaba ang iyong source code, maaari kang magsulat ng dokumentasyon sa isang file ng tulong, na maaaring mai-index o hanapin kasama ng ilang mga keyword. Ang magkahiwalay na mga file ng dokumentasyon ay kapaki-pakinabang kung ang lohika ng programa ay nahahati sa maraming mga pahina at may kasamang mga file ng suporta, tulad ng isang web application.
- Ang ilang mga wika sa programa (tulad ng Java, Visual Basic. NET, o C #) ay may kani-kanilang mga pamantayan sa dokumentasyon ng code. Sa mga ganitong kaso, sundin ang karaniwang dokumentasyon na dapat isama sa source code.
Hakbang 3. Piliin ang naaangkop na tool sa dokumentasyon
Sa ilang mga kaso, ang tool sa dokumentasyon ay natutukoy ng ginamit na wika ng programa. Ang mga wikang C ++, C #, Visual Basic, Java, PHP, at iba pa ay may kani-kanilang mga tool sa dokumentasyon. Gayunpaman, kung hindi, ang mga tool na ginamit ay nakasalalay sa kinakailangang dokumentasyon.
- Ang isang word processor tulad ng Microsoft Word ay angkop para sa paglikha ng mga file ng teksto ng dokumento, basta ang dokumentasyon ay maikli at simple. Upang lumikha ng mahabang dokumentasyon na may kumplikadong teksto, ang karamihan sa mga teknikal na manunulat ay pumili ng isang dalubhasang tool sa dokumentasyon, tulad ng Adobe FrameMaker.
- Ang mga file ng tulong para sa pagdodokumento ng source code ay maaaring malikha gamit ang isang program ng generator file ng suporta, tulad ng RoboHelp, Tulong at Manwal, Doc-To-Help, MadCap Flare, o HelpLogix.
Paraan 2 ng 2: Pagsulat ng Dokumentasyon ng Software para sa Mga End User
Hakbang 1. Alamin ang mga dahilan sa negosyo na pinagbabatayan ng paglikha ng manwal
Habang ang pangunahing dahilan para sa dokumentasyon ng software ay upang matulungan ang mga gumagamit na maunawaan kung paano gamitin ang application, maraming iba pang mga kadahilanan na maaaring maging batayan ng paglikha ng dokumentasyon, tulad ng pagtulong sa departamento ng marketing na ibenta ang application, pagbutihin ang imahe ng kumpanya, at pagbawas ng suportang panteknikal gastos Sa ilang mga kaso, kinakailangan ang dokumentasyon upang sumunod sa mga regulasyon o iba pang mga kinakailangang ligal.
Gayunpaman, ang dokumentasyon ay hindi isang magandang kapalit para sa isang interface. Kung ang isang aplikasyon ay nangangailangan ng maraming dokumentasyon upang mapatakbo, dapat itong idinisenyo upang maging mas madaling maunawaan
Hakbang 2. Alamin ang target na madla ng dokumentasyon
Pangkalahatan, ang mga gumagamit ng software ay may limitadong kaalaman sa computer na lampas sa mga application na ginagamit nila. Mayroong maraming mga paraan upang matugunan ang kanilang mga pangangailangan sa dokumentasyon:
- Bigyang-pansin ang pamagat ng gumagamit ng software. Halimbawa, pangkalahatang naiintindihan ng administrator ng system ang iba't ibang mga aplikasyon ng computer, habang alam lamang ng kalihim ang mga application na ginagamit niya upang maglagay ng data.
- Magbayad ng pansin sa mga gumagamit ng software. Bagaman ang kanilang mga posisyon sa pangkalahatan ay katugma sa mga gawaing isinagawa, ang mga posisyon na ito ay maaaring may iba't ibang mga karga sa trabaho, depende sa lugar ng negosyo. Sa pamamagitan ng pakikipanayam sa mga potensyal na gumagamit, malalaman mo kung tama ang iyong pagtatasa sa kanilang pamagat sa trabaho.
- Bigyang pansin ang mayroon nang dokumentasyon. Maaaring ipakita ng dokumentasyon at pagtutukoy ng pagpapaandar ng software kung ano ang kailangang malaman ng mga gumagamit upang magamit ito. Gayunpaman, tandaan na ang mga gumagamit ay maaaring hindi interesado na malaman ang "loob" ng programa.
- Alamin kung ano ang kinakailangan upang makumpleto ang isang gawain, at kung ano ang kinakailangan bago mo ito makumpleto.
Hakbang 3. Tukuyin ang naaangkop na format para sa dokumentasyon
Ang dokumentasyon ng software ay maaaring isaayos sa 1 o 2 na mga format, katulad ng mga sanggunian na libro at manwal. Minsan, ang pagsasama-sama ng dalawang mga format ay isang mahusay na solusyon.
- Ginagamit ang mga format ng sanggunian upang ilarawan ang lahat ng mga tampok sa software, tulad ng mga pindutan, tab, patlang, at mga kahon ng dayalogo, at kung paano ito gumagana. Ang ilang mga file ng tulong ay nakasulat sa format na ito, lalo na ang mga sensitibo sa konteksto. Kapag nag-click ang gumagamit sa Tulong sa isang tiyak na screen, makakatanggap ang gumagamit ng nauugnay na paksa.
- Ginagamit ang manu-manong format upang ipaliwanag kung paano gumawa ng isang bagay sa software. Ang mga manwal ay pangkalahatang naka-print o format na PDF, bagaman ang ilang mga pahina ng tulong ay nagsasama rin ng mga tagubilin sa kung paano gawin ang ilang mga bagay. (Pangkalahatan, ang mga manu-manong format ay hindi sensitibo sa konteksto, ngunit maaaring maiugnay mula sa mga paksang sensitibo sa konteksto). Ang mga Handbook ay karaniwang nasa anyo ng isang gabay, na may buod ng mga gawain na isasagawa sa isang paglalarawan at isang gabay na na-format sa mga hakbang.
Hakbang 4. Magpasya sa uri ng dokumentasyon
Ang dokumentasyon ng software para sa mga gumagamit ay maaaring ibinalot sa isa o higit pa sa mga sumusunod na format: naka-print na manwal, mga PDF file, mga file ng tulong, o tulong sa online. Ang bawat uri ng dokumentasyon ay idinisenyo upang maipakita sa iyo kung paano gamitin ang mga pagpapaandar ng software, maging ito man ay isang gabay o isang tutorial. Ang mga online na dokumentasyon at pahina ng tulong ay maaari ring magsama ng mga demonstration video, teksto, at mga static na imahe.
Ang mga online na tulong at suporta ng mga file ay dapat na ma-index at mahahanap gamit ang mga keyword upang mabilis na mahanap ng mga gumagamit ang impormasyong kailangan nila. Bagaman ang isang application ng help file generator ay maaaring awtomatikong lumikha ng isang index, inirerekumenda pa rin na lumikha ka ng isang indeks nang manu-mano gamit ang mga karaniwang hinanap na keyword
Hakbang 5. Piliin ang naaangkop na tool sa dokumentasyon
Ang mga naka-print na manwal o PDF ay maaaring likhain ng isang programa sa pagpoproseso ng salita tulad ng Word o isang advanced na editor ng teksto tulad ng FrameMaker, depende sa haba at pagiging kumplikado ng file. Ang mga file ng tulong ay maaaring nakasulat sa isang programa ng paglikha ng file ng tulong, tulad ng RoboHelp, Tulong at Manwal, Doc-To-Help, Flare, HelpLogix, o HelpServer.
Mga Tip
- Ang teksto ng dokumentasyon ng programa ay dapat na nakaayos sa isang paraan na madaling basahin. Ilagay ang imahe nang malapit sa naaangkop na teksto hangga't maaari. Masira ang dokumentasyon ayon sa mga seksyon at paksa nang lohikal. Ang bawat seksyon o paksa ay dapat na naglalarawan ng isang tukoy na problema, kapwa mga tampok sa gawain at programa. Ang mga nauugnay na isyu ay maaaring ipaliwanag sa mga link o listahan ng sanggunian.
- Ang bawat isa sa mga tool sa dokumentasyon na inilarawan sa artikulong ito ay maaaring pupunan ng isang programang gumagawa ng screenshot, tulad ng SnagIt kung ang iyong dokumentasyon ay nangangailangan ng maraming mga screenshot. Tulad ng anumang iba pang dokumentasyon, dapat mo ring isama ang mga screenshot upang makatulong na ipaliwanag kung paano gumagana ang app, sa halip na "akitin" ang gumagamit.
- Ang pagbibigay pansin sa istilo ay napakahalaga, lalo na kung nagsusulat ka ng dokumentasyon ng software para sa mga end user. Address sa mga gumagamit ng panghalip na "ikaw", sa halip na "gumagamit".
