კარგი პროგრამული უზრუნველყოფის დოკუმენტაცია, იქნება ეს პროგრამისტებისა და შემმოწმებლების სპეციფიკაციის დოკუმენტაცია, ტექნიკური დოკუმენტები შიდა მომხმარებლებისთვის, თუ სახელმძღვანელოები და საბოლოო ფაილების დამხმარე ფაილები, დაეხმარება მომხმარებლებს გაიგონ პროგრამული უზრუნველყოფის მახასიათებლები და ფუნქციები. კარგი დოკუმენტაცია არის დოკუმენტაცია, რომელიც არის კონკრეტული, მკაფიო და შესაბამისი, მომხმარებლისთვის საჭირო ყველა ინფორმაციის მქონე. ეს სტატია დაგეხმარებათ დაწეროთ პროგრამული უზრუნველყოფის დოკუმენტაცია ტექნიკური მომხმარებლებისა და საბოლოო მომხმარებლებისთვის.
ნაბიჯი
მეთოდი 1 დან 2: ტექნიკური მომხმარებლისათვის პროგრამული უზრუნველყოფის დოკუმენტაციის წერა
ნაბიჯი 1. იცოდეთ რა ინფორმაცია უნდა შეიცავდეს
სპეციფიკაციის დოკუმენტი გამოიყენება როგორც საცნობარო სახელმძღვანელო ინტერფეისის დიზაინერებისთვის, პროგრამისტებისთვის, რომლებიც წერენ კოდს და შემმოწმებლებს, რომლებიც ამოწმებენ პროგრამული უზრუნველყოფის მუშაობას. ინფორმაცია, რომელიც უნდა შეიცავდეს, დამოკიდებული იქნება პროგრამის შექმნაზე, მაგრამ შეიძლება შეიცავდეს შემდეგს:
- პროგრამის მნიშვნელოვანი ფაილები, როგორიცაა განვითარების ჯგუფის მიერ შექმნილი ფაილები, პროგრამის მუშაობისას წვდომა მონაცემთა ბაზებზე და მესამე მხარის პროგრამები.
- ფუნქციები და ქვეგეგმები, მათ შორის ფუნქციის/ქვეგეგმის, შეყვანის და გამომავალი მნიშვნელობების გამოყენების ახსნა.
- პროგრამის ცვლადები და მუდმივები და მათი გამოყენება.
- პროგრამის საერთო სტრუქტურა. დისკზე დაფუძნებული პროგრამებისთვის შეიძლება დაგჭირდეთ თითოეული მოდულის და ბიბლიოთეკის აღწერა. ან, თუ თქვენ წერთ სახელმძღვანელოს ვებ პროგრამისთვის, შეიძლება დაგჭირდეთ ახსნა, თუ რომელ ფაილებს იყენებს თითოეული გვერდი.
ნაბიჯი 2. გადაწყვიტეთ რა დონის დოკუმენტაცია უნდა იყოს წარმოდგენილი და გამოყოფილი პროგრამის კოდისგან
რაც უფრო მეტი ტექნიკური დოკუმენტაცია შედის პროგრამის კოდში, მით უფრო ადვილი იქნება მისი განახლება და შენარჩუნება, ასევე პროგრამის სხვადასხვა ვერსიის ახსნა. პროგრამის კოდში არსებული დოკუმენტაცია უნდა შეიცავდეს ფუნქციების, ქვეგეგმების, ცვლადების და მუდმივების გამოყენებას.
- თუ თქვენი საწყისი კოდი გრძელია, შეგიძლიათ ჩაწეროთ დოკუმენტაცია დამხმარე ფაილში, რომლის ინდექსირება ან ძიება შესაძლებელია გარკვეული საკვანძო სიტყვებით. ცალკეული დოკუმენტაციის ფაილები სასარგებლოა, თუ პროგრამის ლოგიკა იყოფა რამდენიმე გვერდზე და მოიცავს დამხმარე ფაილებს, როგორიცაა ვებ პროგრამა.
- ზოგიერთ პროგრამირების ენას (როგორიცაა Java, Visual Basic. NET ან C#) აქვს საკუთარი კოდის დოკუმენტაციის სტანდარტები. ასეთ შემთხვევებში მიჰყევით სტანდარტულ დოკუმენტაციას, რომელიც უნდა შედიოდეს წყაროს კოდში.
ნაბიჯი 3. აირჩიეთ შესაბამისი დოკუმენტაციის ინსტრუმენტი
ზოგიერთ შემთხვევაში, დოკუმენტაციის ინსტრუმენტი განისაზღვრება გამოყენებული პროგრამირების ენით. ენებს C ++, C#, Visual Basic, Java, PHP და სხვა აქვთ დოკუმენტაციის საკუთარი ინსტრუმენტები. თუმცა, თუ არა, გამოყენებული ინსტრუმენტები დამოკიდებული იქნება საჭირო დოკუმენტაციაზე.
- ტექსტური პროცესორი, როგორიცაა Microsoft Word, შესაფერისია დოკუმენტის ტექსტური ფაილების შესაქმნელად, თუ დოკუმენტაცია არის მოკლე და მარტივი. რთული ტექსტით გრძელი დოკუმენტაციის შესაქმნელად, ტექნიკური მწერლების უმეტესობა ირჩევს სპეციალიზირებულ დოკუმენტაციის ინსტრუმენტს, მაგალითად Adobe FrameMaker.
- წყაროს კოდის დოკუმენტირებისათვის დამხმარე ფაილების შექმნა შესაძლებელია დამხმარე ფაილების გენერატორის პროგრამით, როგორიცაა RoboHelp, Help and Manual, Doc-to-Help, MadCap Flare ან HelpLogix.
მეთოდი 2 2: პროგრამული დოკუმენტაციის წერა საბოლოო მომხმარებლისთვის
ნაბიჯი 1. იცოდეთ ბიზნეს მიზეზები, რომლებიც ემყარება სახელმძღვანელოს შექმნას
მიუხედავად იმისა, რომ პროგრამული უზრუნველყოფის დოკუმენტაციის მთავარი მიზეზი არის დაეხმაროს მომხმარებლებს გაიგონ, როგორ გამოიყენონ პროგრამა, არსებობს რამდენიმე სხვა მიზეზი, რამაც შეიძლება ხელი შეუწყოს დოკუმენტაციის შექმნას, როგორიცაა მარკეტინგის განყოფილების დახმარება პროგრამის გაყიდვაში, კომპანიის იმიჯის გაუმჯობესება და ტექნიკური დახმარების შემცირება. ღირს. ზოგიერთ შემთხვევაში, დოკუმენტაციაა საჭირო რეგულაციების ან სხვა სამართლებრივი მოთხოვნების შესასრულებლად.
ამასთან, დოკუმენტაცია არ არის ინტერფეისის კარგი შემცვლელი. თუ აპლიკაცია მოითხოვს უამრავ დოკუმენტაციას, ის უნდა იყოს უფრო ინტუიციური
ნაბიჯი 2. იცოდეთ დოკუმენტაციის სამიზნე აუდიტორია
საერთოდ, პროგრამული უზრუნველყოფის მომხმარებლებს აქვთ შეზღუდული კომპიუტერული ცოდნა მათ მიერ გამოყენებული პროგრამების მიღმა. მათი დოკუმენტაციის მოთხოვნილებების დაკმაყოფილების რამდენიმე გზა არსებობს:
- ყურადღება მიაქციეთ პროგრამის მომხმარებლის სათაურს. მაგალითად, სისტემის ადმინისტრატორს ზოგადად ესმის სხვადასხვა კომპიუტერული პროგრამები, ხოლო მდივანმა იცის მხოლოდ ის პროგრამები, რომლებსაც იყენებს მონაცემების შესასვლელად.
- ყურადღება მიაქციეთ პროგრამული უზრუნველყოფის მომხმარებლებს. მიუხედავად იმისა, რომ მათი პოზიციები ზოგადად თავსებადია შესრულებულ ამოცანებთან, ამ პოზიციებს შეიძლება ჰქონდეთ განსხვავებული დატვირთვა, ბიზნესის ადგილის მიხედვით. პოტენციურ მომხმარებლებთან გასაუბრებით შეგიძლიათ გაარკვიოთ, სწორია თუ არა თქვენი სამუშაო სახელის შეფასება.
- ყურადღება მიაქციეთ არსებულ დოკუმენტაციას. პროგრამული უზრუნველყოფის ფუნქციონირების დოკუმენტაციას და სპეციფიკაციებს შეუძლიათ აჩვენონ ის, რაც მომხმარებლებმა უნდა იცოდნენ მათი გამოყენებისათვის. თუმცა, გახსოვდეთ, რომ მომხმარებლებს შეიძლება არ აინტერესებდეთ პროგრამის "შინაგანი" ცოდნა.
- იცოდეთ რა არის საჭირო დავალების შესასრულებლად და რა არის საჭირო მისი დასრულების წინ.
ნაბიჯი 3. დოკუმენტაციის შესაბამისი ფორმატის განსაზღვრა
პროგრამული უზრუნველყოფის დოკუმენტაცია შეიძლება განლაგდეს 1 ან 2 ფორმატში, კერძოდ საცნობარო წიგნებში და სახელმძღვანელოებში. ზოგჯერ, ორი ფორმატის გაერთიანება კარგი გამოსავალია.
- საცნობარო ფორმატები გამოიყენება პროგრამული უზრუნველყოფის ყველა მახასიათებლის აღსაწერად, როგორიცაა ღილაკები, ჩანართები, ველები და დიალოგური ფანჯრები და როგორ მუშაობს ისინი. ზოგიერთი დამხმარე ფაილი იწერება ამ ფორმატში, განსაკუთრებით ის, რაც კონტექსტის მიმართ მგრძნობიარეა. როდესაც მომხმარებელი დააჭერს დახმარებას გარკვეულ ეკრანზე, მომხმარებელი მიიღებს შესაბამის თემას.
- სახელმძღვანელო ფორმატი გამოიყენება იმის ახსნის, თუ როგორ უნდა გააკეთოთ რაიმე პროგრამული უზრუნველყოფით. სახელმძღვანელოები, როგორც წესი, დაბეჭდილია ან PDF ფორმატში, თუმცა ზოგიერთი დამხმარე გვერდი ასევე შეიცავს მითითებებს, თუ როგორ უნდა გავაკეთოთ რაღაცეები. (საერთოდ, სახელმძღვანელო ფორმატები არ არის მგრძნობიარე კონტექსტში, მაგრამ შეიძლება დაკავშირებული იყოს კონტექსტისადმი მგრძნობიარე თემებიდან). სახელმძღვანელოები, როგორც წესი, არის სახელმძღვანელოს სახით, სადაც მოცემულია დავალებების შეჯამება აღწერილობაში და გზამკვლევი, რომელიც ეტაპობრივად არის ფორმატირებული.
ნაბიჯი 4. გადაწყვიტეთ დოკუმენტაციის ტიპი
პროგრამული უზრუნველყოფის დოკუმენტაცია მომხმარებლებისთვის შეიძლება შეფუთული იყოს ერთი ან რამდენიმე შემდეგი ფორმატით: დაბეჭდილი სახელმძღვანელოები, PDF ფაილები, დამხმარე ფაილები ან ონლაინ დახმარება. თითოეული სახის დოკუმენტაცია შექმნილია იმისთვის, რომ გაჩვენოთ თუ როგორ გამოიყენოთ პროგრამული უზრუნველყოფის ფუნქციები, იქნება ეს სახელმძღვანელო თუ სამეურვეო. ონლაინ დოკუმენტაცია და დახმარების გვერდები შეიძლება შეიცავდეს სადემონსტრაციო ვიდეოებს, ტექსტს და სტატიკურ სურათებს.
ონლაინ დახმარებისა და დამხმარე ფაილები უნდა იყოს ინდექსირებული და საძიებელი საკვანძო სიტყვების გამოყენებით, რათა მომხმარებლებმა სწრაფად მოიძიონ საჭირო ინფორმაცია. მიუხედავად იმისა, რომ დამხმარე ფაილების გენერატორის პროგრამას შეუძლია ავტომატურად შექმნას ინდექსი, მაინც არის რეკომენდებული ინდექსის ხელით შექმნა საყოველთაოდ ძებნილი საკვანძო სიტყვების გამოყენებით
ნაბიჯი 5. შეარჩიეთ შესაბამისი დოკუმენტაციის ინსტრუმენტი
დაბეჭდილი სახელმძღვანელოები ან PDF– ები შეიძლება შეიქმნას ტექსტის დამუშავების პროგრამით, როგორიცაა Word ან მოწინავე ტექსტური რედაქტორი, როგორიცაა FrameMaker, ფაილის სიგრძისა და სირთულის მიხედვით. დახმარების ფაილების ჩაწერა შესაძლებელია დამხმარე ფაილის შექმნის პროგრამით, როგორიცაა RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix ან HelpServer.
Რჩევები
- პროგრამის დოკუმენტაციის ტექსტი უნდა იყოს სტრუქტურირებული ისე, რომ მისი წაკითხვა ადვილი იყოს. მოათავსეთ სურათი რაც შეიძლება ახლოს შესაბამის ტექსტთან. ლოგიკურად დაყავით დოკუმენტაცია სექციებისა და თემების მიხედვით. თითოეული განყოფილება ან თემა უნდა აღწეროს კონკრეტულ პრობლემას, როგორც ამოცანას, ასევე პროგრამის მახასიათებლებს. დაკავშირებული საკითხები შეიძლება აიხსნას ბმულებით ან საცნობარო სიებით.
- ამ სტატიაში აღწერილი დოკუმენტაციის თითოეული ინსტრუმენტი შეიძლება შეავსოს ეკრანის გადაღების პროგრამით, როგორიცაა SnagIt, თუ თქვენი დოკუმენტაცია მოითხოვს რამოდენიმე ეკრანის სურათს. ნებისმიერი სხვა დოკუმენტაციის მსგავსად, თქვენ ასევე უნდა შეიცავდეს ეკრანის ანაბეჭდებს, რათა დაგეხმაროთ აგიხსნათ, თუ როგორ მუშაობს აპლიკაცია, ვიდრე მომხმარებლის "მოტყუება".
- სტილისთვის ყურადღების გამახვილება ძალიან მნიშვნელოვანია, განსაკუთრებით იმ შემთხვევაში, თუ თქვენ წერთ პროგრამულ დოკუმენტაციას საბოლოო მომხმარებლისთვის. მიმართეთ მომხმარებლებს ნაცვალსახელით "თქვენ", ნაცვლად "მომხმარებლის".
