Dokumentacioni i mirë i softuerit, qoftë dokumentacioni i specifikimit për programuesit dhe testuesit, dokumentet teknike për përdoruesit e brendshëm, ose manualet dhe skedarët ndihmës për përdoruesit përfundimtarë, do t'i ndihmojë përdoruesit të kuptojnë veçoritë dhe funksionet e softuerit. Dokumentacioni i mirë është dokumentacioni që është specifik, i qartë dhe i rëndësishëm, me të gjithë informacionin që i nevojitet përdoruesit. Ky artikull do t'ju udhëzojë të shkruani dokumentacionin e softuerit për përdoruesit teknikë dhe përdoruesit përfundimtarë.
Hapi
Metoda 1 nga 2: Shkrimi i Dokumentacionit të Softuerit për Përdoruesit Teknikë
Hapi 1. Di se çfarë informacioni duhet të përfshish
Dokumenti i specifikimit përdoret si një manual referimi për projektuesit e ndërfaqeve, programuesit që shkruajnë kod dhe testuesit që verifikojnë performancën e softuerit. Informacioni që duhet të përfshihet do të varet nga programi që krijohet, por mund të përfshijë sa vijon:
- Skedarë të rëndësishëm në aplikacion, siç janë skedarët e krijuar nga ekipi i zhvillimit, bazat e të dhënave të aksesuara gjatë funksionimit të programit dhe aplikacionet e palëve të treta.
- Funksionet dhe nën -rutinat, duke përfshirë një shpjegim të përdorimit të funksionit/nënrutinës, vlerat e hyrjes dhe daljes.
- Variablat dhe konstantet e programit, dhe si përdoren ato.
- Struktura e përgjithshme e programit. Për programet e bazuara në makinë, mund t'ju duhet të përshkruani secilin modul dhe bibliotekë. Ose, nëse jeni duke shkruar një manual për një program të bazuar në ueb, mund t'ju duhet të shpjegoni se cilat skedarë përdor secila faqe.
Hapi 2. Vendosni se çfarë niveli dokumentacioni duhet të jetë i pranishëm dhe i ndarë nga kodi i programit
Sa më shumë dokumentacion teknik të përfshihet në kodin e programit, aq më e lehtë do të jetë përditësimi dhe mirëmbajtja e tij, si dhe shpjegimi i versioneve të ndryshme të programit. Së paku, dokumentacioni në kodin e programit duhet të përfshijë përdorimin e funksioneve, nënrutinave, ndryshoreve dhe konstanteve.
- Nëse kodi juaj burimor është i gjatë, mund të shkruani dokumentacion në një skedar ndihme, i cili më pas mund të indeksohet ose të kërkohet me fjalë kyçe të caktuara. Skedarët e veçantë të dokumentacionit janë të dobishëm nëse logjika e programit është e ndarë në disa faqe dhe përfshin skedarë mbështetës, siç është një aplikacion në internet.
- Disa gjuhë programimi (si Java, Visual Basic. NET ose C#) kanë standardet e tyre të dokumentacionit të kodit. Në raste të tilla, ndiqni dokumentacionin standard që duhet të përfshihet në kodin burimor.
Hapi 3. Zgjidhni mjetin e duhur të dokumentacionit
Në disa raste, mjeti i dokumentacionit përcaktohet nga gjuha e programimit e përdorur. Gjuhët C ++, C#, Visual Basic, Java, PHP dhe të tjerët kanë mjetet e tyre të dokumentacionit. Sidoqoftë, nëse jo, mjetet e përdorura do të varen nga dokumentacioni i kërkuar.
- Një përpunues teksti si Microsoft Word është i përshtatshëm për krijimin e skedarëve të tekstit të dokumentit, përderisa dokumentacioni është konciz dhe i thjeshtë. Për të krijuar dokumentacion të gjatë me tekst kompleks, shumica e shkrimtarëve teknikë zgjedhin një mjet të specializuar dokumentacioni, siç është Adobe FrameMaker.
- Skedarët e ndihmës për dokumentimin e kodit burimor mund të krijohen me një program gjenerues të skedarëve mbështetës, të tillë si RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare ose HelpLogix.
Metoda 2 nga 2: Shkrimi i Dokumentacionit të Softuerit për Përdoruesit Fundorë
Hapi 1. Njihni arsyet e biznesit që qëndrojnë në themel të krijimit të manualit
Ndërsa arsyeja kryesore për dokumentacionin e softuerit është të ndihmojë përdoruesit të kuptojnë se si të përdorin aplikacionin, ka disa arsye të tjera që mund të jenë në themel të krijimit të dokumentacionit, të tilla si ndihma e departamentit të marketingut për të shitur aplikacionin, përmirësimi i imazhit të kompanisë dhe zvogëlimi i mbështetjes teknike shpenzimet. Në disa raste, dokumentacioni kërkohet për të qenë në përputhje me rregulloret ose kërkesat e tjera ligjore.
Sidoqoftë, dokumentacioni nuk është një zëvendësues i mirë për një ndërfaqe. Nëse një aplikacion kërkon shumë dokumentacion për të funksionuar, ai duhet të jetë i dizajnuar që të jetë më intuitiv
Hapi 2. Njihni audiencën e synuar të dokumentacionit
Në përgjithësi, përdoruesit e softuerit kanë njohuri të kufizuara kompjuterike përtej aplikacioneve të përdorura prej tyre. Ka disa mënyra për të plotësuar nevojat e tyre të dokumentacionit:
- Kushtojini vëmendje titullit të përdoruesit të softuerit. Për shembull, administratori i sistemit në përgjithësi kupton aplikacione të ndryshme kompjuterike, ndërsa sekretari i njeh vetëm aplikacionet që ai përdor për të futur të dhëna.
- Kushtojini vëmendje përdoruesve të softuerit. Edhe pse pozicionet e tyre në përgjithësi janë në përputhje me detyrat e kryera, këto pozicione mund të kenë ngarkesa të ndryshme pune, në varësi të vendit të biznesit. Duke intervistuar përdoruesit e mundshëm, mund të zbuloni nëse vlerësimi juaj për titullin e punës së tyre është i saktë.
- Kushtojini vëmendje dokumentacionit ekzistues. Dokumentacioni dhe specifikimet e funksionalitetit të softuerit mund të tregojnë atë që përdoruesit duhet të dinë për t'i përdorur ato. Sidoqoftë, mbani në mend se përdoruesit mund të mos jenë të interesuar të dinë "brendësinë" e programit.
- Dije se çfarë duhet për të përfunduar një detyrë dhe çfarë duhet para se ta përfundosh.
Hapi 3. Përcaktoni formatin e duhur për dokumentacionin
Dokumentacioni i softverit mund të organizohet në 1 ose 2 formate, përkatësisht libra referues dhe manuale. Ndonjëherë, kombinimi i dy formateve është një zgjidhje e mirë.
- Formatet e referencës përdoren për të përshkruar të gjitha tiparet e softuerit, të tilla si butonat, skedat, fushat dhe kutitë e dialogut dhe mënyrën e funksionimit të tyre. Disa skedarë ndihme janë shkruar në këtë format, veçanërisht ato që janë të ndjeshëm ndaj kontekstit. Kur përdoruesi klikon në Ndihmë në një ekran të caktuar, përdoruesi do të marrë temën përkatëse.
- Formati manual përdoret për të shpjeguar se si të bëni diçka me softuerin. Manualet janë përgjithësisht në format të shtypur ose PDF, megjithëse disa faqe ndihme përfshijnë gjithashtu udhëzime se si të bëni gjëra të caktuara. (Në përgjithësi, formatet manuale nuk janë të ndjeshme ndaj kontekstit, por mund të lidhen nga tema të ndjeshme ndaj kontekstit). Doracakët janë përgjithësisht në formën e një udhëzuesi, me një përmbledhje të detyrave që duhet të kryhen në një përshkrim dhe një udhëzues të formatuar në hapa.
Hapi 4. Vendosni për llojin e dokumentacionit
Dokumentacioni softuerik për përdoruesit mund të paketohet në një ose më shumë nga format e mëposhtme: manuale të printuara, skedarë PDF, skedarë ndihme ose ndihmë online. Çdo lloj dokumentacioni është krijuar për t'ju treguar se si të përdorni funksionet e softuerit, pavarësisht nëse është udhëzues apo udhëzues. Dokumentacioni online dhe faqet e ndihmës mund të përfshijnë gjithashtu video demonstruese, tekst dhe imazhe statike.
Skedarët e ndihmës dhe mbështetjes në internet duhet të indeksohen dhe të kërkohen duke përdorur fjalë kyçe në mënyrë që përdoruesit të gjejnë shpejt informacionin që u nevojitet. Edhe pse një aplikacion i gjeneruesit të skedarëve të ndihmës mund të krijojë një indeks automatikisht, përsëri rekomandohet që të krijoni një indeks me dorë duke përdorur fjalë kyçe të kërkuara zakonisht
Hapi 5. Zgjidhni mjetin e duhur të dokumentacionit
Manualet e printuara ose PDF mund të krijohen me një program të përpunimit të tekstit si Word ose një redaktues teksti të avancuar siç është FrameMaker, në varësi të gjatësisë dhe kompleksitetit të skedarit. Skedarët e ndihmës mund të shkruhen me një program krijimi të skedarëve të ndihmës, të tilla si RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix ose HelpServer.
Këshilla
- Teksti i dokumentacionit të programit duhet të jetë i strukturuar në atë mënyrë që të lexohet lehtë. Vendoseni imazhin sa më afër tekstit të përshtatshëm. Ndani dokumentacionin sipas seksioneve dhe temave në mënyrë logjike. Çdo seksion ose temë duhet të përshkruajë një problem specifik, si detyrat ashtu edhe veçoritë e programit. Çështjet e ndërlidhura mund të shpjegohen me lidhje ose lista referimi.
- Secili nga mjetet e dokumentacionit të përshkruar në këtë artikull mund të plotësohet me një program krijues të pamjeve të ekranit, siç është SnagIt nëse dokumentacioni juaj kërkon fotografi të shumta të ekranit. Ashtu si çdo dokumentacion tjetër, ju gjithashtu duhet të përfshini fotografi të ekranit për të ndihmuar në shpjegimin se si funksionon aplikacioni, në vend që të "josheni" përdoruesin.
- Vëmendja ndaj stilit është shumë e rëndësishme, veçanërisht nëse jeni duke shkruar dokumentacionin e softuerit për përdoruesit përfundimtarë. Drejtojuni përdoruesve me përemrin "ju", në vend të "përdoruesit".
