Бағдарламалық қамтамасыз етудің жақсы құжаттамасы, ол бағдарламашылар мен тестерлерге арналған техникалық құжаттама болсын, ішкі пайдаланушыларға арналған техникалық құжаттар болсын, соңғы пайдаланушыларға арналған нұсқаулықтар мен анықтамалық файлдар болсын, пайдаланушыларға бағдарламалық қамтамасыз етудің мүмкіндіктері мен функцияларын түсінуге көмектеседі. Жақсы құжаттама - бұл пайдаланушыға қажет барлық ақпаратпен нақты, түсінікті және сәйкес құжаттама. Бұл мақала техникалық пайдаланушыларға және соңғы пайдаланушыларға арналған бағдарламалық қамтамасыз ету құжаттамасын жазуға көмектеседі.
Қадам
2 әдісі 1: Техникалық пайдаланушыларға арналған бағдарламалық қамтамасыз ету құжаттарын жазу
Қадам 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 форматта орналастыруға болады, атап айтқанда анықтамалықтар мен нұсқаулықтар. Кейде екі форматты біріктіру жақсы шешім болады.
- Анықтамалық форматтар батырмалар, қойындылар, өрістер мен диалогтық терезелер сияқты бағдарламалық қамтамасыз етудің барлық мүмкіндіктерін және олардың қалай жұмыс істейтінін сипаттау үшін қолданылады. Кейбір анықтамалық файлдар осы форматта жазылған, әсіресе контекстке сезімтал файлдар. Пайдаланушы белгілі бір экранда Help (Анықтама) түймесін басқанда, пайдаланушы тиісті тақырыпты алады.
- Қолмен форматтау бағдарламалық жасақтамамен бір нәрсені қалай жасау керектігін түсіндіру үшін қолданылады. Нұсқаулықтар әдетте баспа немесе PDF форматында болады, дегенмен кейбір анықтамалық беттерде кейбір әрекеттерді орындау бойынша нұсқаулықтар бар. (Әдетте, қолмен пішімдер мәтінмәнге сезімтал емес, бірақ контекстке сезімтал тақырыптардан байланыстырылуы мүмкін). Анықтамалықтар әдетте нұсқаулық түрінде болады, сипаттамада орындалатын міндеттердің қысқаша мазмұны және қадаммен пішімделген нұсқаулық.
Қадам 4. Құжаттаманың түрі туралы шешім қабылдаңыз
Пайдаланушыларға арналған бағдарламалық қамтамасыз ету құжаттамасы келесі форматтардың бірінде немесе бірнешеуінде болуы мүмкін: басылған нұсқаулықтар, PDF файлдары, анықтама файлдары немесе желідегі анықтама. Құжаттардың әр түрі сізге нұсқаулық немесе оқулық болсын, бағдарламалық қамтамасыз етудің функцияларын қалай пайдалану керектігін көрсетуге арналған. Онлайн құжаттама мен анықтама беттерінде демонстрациялық бейнелер, мәтіндер мен статикалық суреттер де болуы мүмкін.
Қолданушылар қажетті ақпаратты тез табуы үшін желідегі анықтама мен қолдау файлдарын индекстеу және кілт сөздерді пайдаланып іздеу керек. Анықтамалық файл генераторы қосымшасы индексті автоматты түрде құра алатынына қарамастан, әлі де жиі ізделетін кілт сөздерді пайдаланып индексті қолмен жасау ұсынылады
Қадам 5. Сәйкес құжаттама құралын таңдаңыз
Басып шығарылған нұсқаулықтар немесе PDF форматтары файлдың ұзындығы мен күрделілігіне қарай Word немесе мәтіндік өңдеуші FrameMaker сияқты мәтін өңдеуші бағдарламаның көмегімен жасалуы мүмкін. Анықтама файлдарын RoboHelp, Help and Manual, Doc-to-Help, Flare, HelpLogix немесе HelpServer сияқты анықтама файлдарын құру бағдарламасымен жазуға болады.
Кеңестер
- Бағдарламалық құжаттаманың мәтіні оқуға ыңғайлы болатындай етіп құрылуы керек. Суретті сәйкес мәтінге мүмкіндігінше жақын орналастырыңыз. Құжаттарды бөлімдер мен тақырыптар бойынша логикалық түрде бөліңіз. Әр бөлім немесе тақырып белгілі бір мәселені, тапсырманың да, бағдарламаның да мүмкіндіктерін сипаттауы тиіс. Қатысты мәселелерді сілтемелермен немесе сілтемелер тізімімен түсіндіруге болады.
- Осы мақалада сипатталған құжаттама құралдарының әрқайсысы, егер сіздің құжаттамаңызға бірнеше скриншот қажет болса, SnagIt сияқты скриншот жасаушы бағдарламамен толықтырылуы мүмкін. Кез келген басқа құжат сияқты, сіз де қолданушыны «алдаудың» орнына, қосымшаның қалай жұмыс істейтінін түсіндіруге көмектесетін скриншоттарды қосуыңыз керек.
- Стильге назар аудару өте маңызды, әсіресе егер сіз соңғы пайдаланушыларға арналған бағдарламалық жасақтама құжаттамасын жазсаңыз. Қолданушыларға «пайдаланушы» орнына «сіз» есімдігі арқылы хабарласыңыз.
