Yaxshi dasturiy hujjatlar, xoh dasturchilar va testerlar uchun spetsifikatsiya hujjatlari, xoh ichki foydalanuvchilar uchun texnik hujjatlar, ham qo'llanmalar va oxirgi foydalanuvchilar uchun yordam fayllari bo'lsin, foydalanuvchilarga dasturiy ta'minotning xususiyatlari va funktsiyalarini tushunishga yordam beradi. Yaxshi hujjat - bu foydalanuvchiga kerak bo'lgan barcha ma'lumotlarga ega bo'lgan aniq, aniq va tegishli hujjatlar. Ushbu maqola sizga texnik foydalanuvchilar va oxirgi foydalanuvchilar uchun dasturiy hujjatlarni yozishga yordam beradi.
Qadam
2 -usul 1: Texnik foydalanuvchilar uchun dasturiy hujjatlar yozish
Qadam 1. Qaysi ma'lumotlarni kiritish kerakligini biling
Xususiyat hujjati interfeys dizaynerlari, kod yozuvchi dasturchilar va dasturiy ta'minot ishini tekshiruvchi testerlar uchun qo'llanma sifatida ishlatiladi. Qo'shilishi kerak bo'lgan ma'lumotlar yaratilgan dasturga bog'liq bo'ladi, lekin quyidagilarni o'z ichiga olishi mumkin.
- Ilovadagi muhim fayllar, masalan, ishlab chiqish guruhi tomonidan yaratilgan fayllar, dastur ishlayotgan vaqtda kiriladigan ma'lumotlar bazalari va uchinchi tomon dasturlari.
- Vazifalar va kichik dasturlar, shu jumladan funktsiyani/dasturni ishlatilishini tushuntirish, kirish va chiqish qiymatlari.
- Dastur o'zgaruvchilari va konstantalari va ular qanday ishlatilishini.
- Dasturning umumiy tuzilishi. Drayvga asoslangan dasturlar uchun siz har bir modul va kutubxonani tavsiflashingiz kerak bo'lishi mumkin. Yoki, agar siz veb-ga asoslangan dastur uchun qo'llanma yozayotgan bo'lsangiz, har bir sahifada qaysi fayllardan foydalanilishini tushuntirishingiz kerak bo'ladi.
Qadam 2. Qaysi darajadagi hujjatlar bo'lishi va dastur kodidan ajratilishi kerakligini hal qiling
Dastur kodiga qanchalik ko'p texnik hujjatlar kiritilgan bo'lsa, uni yangilash va saqlash, shuningdek dasturning turli xil versiyalarini tushuntirish osonroq bo'ladi. Hech bo'lmaganda, dastur kodidagi hujjatlar funktsiyalar, kichik dasturlar, o'zgaruvchilar va doimiylardan foydalanishni o'z ichiga olishi kerak.
- Agar sizning manba kodingiz uzun bo'lsa, siz hujjatlarni yordam fayliga yozishingiz mumkin, keyin ularni kalit so'zlar yordamida indekslash yoki qidirish mumkin. Alohida hujjat fayllari, agar dastur mantig'i bir nechta sahifalarga bo'lingan bo'lsa va qo'llab -quvvatlash fayllari, masalan, veb -ilovalar bo'lsa, foydalidir.
- Ba'zi dasturlash tillari (Java, Visual Basic. NET yoki C#kabi) o'z kod hujjatlari standartlariga ega. Bunday hollarda, manba kodiga kiritilishi kerak bo'lgan standart hujjatlarga amal qiling.
Qadam 3. Tegishli hujjatlar vositasini tanlang
Ba'zi hollarda hujjatlashtirish vositasi ishlatilgan dasturlash tili bilan belgilanadi. C ++, C#, Visual Basic, Java, PHP va boshqa tillar o'z hujjatlariga ega. Ammo, agar bo'lmasa, ishlatiladigan vositalar kerakli hujjatlarga bog'liq bo'ladi.
- Hujjatlar qisqa va sodda bo'lsa, Microsoft Word kabi matnli protsessor hujjat matnli fayllarini yaratishga mos keladi. Murakkab matnli uzun hujjatlarni yaratish uchun ko'pchilik texnik yozuvchilar Adobe FrameMaker kabi maxsus hujjatlar vositasini tanlaydilar.
- Manba kodini hujjatlashtirish uchun yordam fayllari RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare yoki HelpLogix kabi yordamchi fayllarni ishlab chiqaruvchi dastur yordamida yaratilishi mumkin.
2 -usul 2: Oxirgi foydalanuvchilar uchun dasturiy hujjatlar yozish
Qadam 1. Qo'llanma yaratilishining asosiy sabablarini bilib oling
Dasturiy hujjatlashtirishning asosiy sababi foydalanuvchilarga ilovadan qanday foydalanishni tushunishga yordam berish bo'lsa -da, hujjatlarni yaratishda boshqa bir qancha sabablar bor, masalan, marketing bo'limiga dasturni sotish, kompaniyaning obro'sini yaxshilash va texnik yordamni kamaytirish. xarajatlar. Ba'zi hollarda, hujjatlar normativ hujjatlar yoki boshqa qonuniy talablarga muvofiq bo'lishi uchun talab qilinadi.
Biroq, hujjatlar interfeys uchun yaxshi o'rnini bosa olmaydi. Agar dastur ishlash uchun ko'plab hujjatlarni talab qilsa, u yanada intuitiv bo'lishi uchun mo'ljallangan bo'lishi kerak
Qadam 2. Hujjatlarning maqsadli auditoriyasini bilish
Qoida tariqasida, dasturiy ta'minot foydalanuvchilari o'zlari bilgan dasturlardan tashqari kompyuter bilimlari cheklangan. Hujjatlarga bo'lgan ehtiyojni qondirishning bir necha yo'li mavjud:
- Dastur foydalanuvchisi nomiga e'tibor bering. Masalan, tizim ma'muri odatda turli xil kompyuter dasturlarini tushunadi, kotib esa faqat ma'lumotlarni kiritish uchun foydalanadigan ilovalarni biladi.
- Dastur foydalanuvchilariga e'tibor bering. Garchi ularning pozitsiyalari odatda bajarilgan vazifalarga mos bo'lsa -da, bu lavozimlar ish joyiga qarab har xil yuklamalarga ega bo'lishi mumkin. Potentsial foydalanuvchilar bilan suhbatlashib, siz ularning lavozim nomiga bergan bahoingiz to'g'riligini bilib olishingiz mumkin.
- Mavjud hujjatlarga e'tibor bering. Hujjatlar va dasturiy ta'minotning funktsional imkoniyatlari ulardan foydalanish uchun foydalanuvchilar nimani bilishi kerakligini ko'rsatishi mumkin. Ammo shuni yodda tutingki, foydalanuvchilar dasturning "ichki qismlari" ni bilishdan manfaatdor bo'lmasligi mumkin.
- Vazifani bajarish uchun nima kerakligini va bajarishdan oldin nima kerakligini biling.
Qadam 3. Hujjatlar uchun mos formatni aniqlang
Dasturiy hujjatlar 1 yoki 2 formatda, ya'ni ma'lumotnomalar va qo'llanmalarda joylashtirilishi mumkin. Ba'zida ikkita formatni birlashtirish yaxshi echim bo'ladi.
- Malumot formatlari tugmachalar, yorliqlar, maydonlar va dialog oynalari kabi dasturiy ta'minotning barcha xususiyatlarini va ular qanday ishlashini tasvirlash uchun ishlatiladi. Ba'zi yordam fayllari, ayniqsa kontekstga sezgir bo'lganlar, ushbu formatda yozilgan. Foydalanuvchi ma'lum bir ekranda Help tugmasini bosganida, foydalanuvchi tegishli mavzuni oladi.
- Qo'l formati dasturiy ta'minot bilan qanday ishlashni tushuntirish uchun ishlatiladi. Qo'llanmalar odatda bosma yoki PDF formatida bo'ladi, garchi ba'zi yordam sahifalarida ba'zi ishlarni bajarish bo'yicha ko'rsatmalar ham mavjud. (Odatda, qo'lda formatlash kontekstga sezgir emas, lekin kontekstga sezgir mavzular bilan bog'lanishi mumkin). Qo'llanmalar odatda qo'llanma shaklida bo'lib, ta'rifda bajarilishi kerak bo'lgan vazifalarning qisqacha tavsifi va ko'rsatma bosqichma -bosqich ko'rsatiladi.
Qadam 4. Hujjatlar turiga qaror bering
Foydalanuvchilar uchun dasturiy hujjatlar bir yoki bir nechta formatlarda to'planishi mumkin: bosma qo'llanmalar, PDF -fayllar, yordam fayllari yoki onlayn yordam. Hujjatlarning har bir turi sizga ko'rsatma yoki o'quv qo'llanmasidan qat'i nazar, dasturiy ta'minot funktsiyalaridan qanday foydalanishni ko'rsatish uchun mo'ljallangan. Onlayn hujjatlar va yordam sahifalarida namoyish videolari, matn va statik tasvirlar ham bo'lishi mumkin.
Foydalanuvchilar kerakli ma'lumotlarni tezda topishi uchun onlayn yordam va qo'llab -quvvatlash fayllari indekslanishi va kalit so'zlar yordamida qidirilishi kerak. Yordamchi fayllarni ishlab chiqaruvchi dastur indeksni avtomatik ravishda yaratishi mumkin bo'lsa -da, odatda qidiriladigan kalit so'zlar yordamida indeksni qo'lda yaratish tavsiya etiladi
Qadam 5. Tegishli hujjatlar vositasini tanlang
Chop etilgan qo'llanmalar yoki PDF -lar, faylning uzunligi va murakkabligiga qarab, Word kabi so'zlarni qayta ishlash dasturi yoki FrameMaker kabi rivojlangan matn muharriri yordamida yaratilishi mumkin. Yordam fayllarini RoboHelp, Help and Manual, Doc-to-Help, Flare, HelpLogix yoki HelpServer kabi yordamchi fayllar yaratish dasturi yordamida yozish mumkin.
Maslahatlar
- Dastur hujjatlari matni o'qilishi oson bo'lgan tarzda tuzilishi kerak. Rasmni iloji boricha mos matnga yaqinroq joylashtiring. Hujjatlarni mantiqiy ravishda bo'limlar va mavzular bo'yicha taqsimlang. Har bir bo'lim yoki mavzu ma'lum bir muammoni tasvirlab berishi kerak, ham vazifa, ham dastur xususiyatlari. Tegishli muammolarni havolalar yoki ma'lumotnomalar ro'yxati orqali tushuntirish mumkin.
- Ushbu maqolada tasvirlangan har bir hujjat vositasi, agar sizning hujjatlaringiz bir nechta skrinshotni talab qilsa, SnagIt kabi skrinshot yaratuvchi dastur bilan to'ldirilishi mumkin. Boshqa hujjatlar singari, siz ham foydalanuvchini "aldash" emas, balki uning qanday ishlashini tushuntirish uchun ekran tasvirlarini qo'shishingiz kerak.
- Uslubga e'tibor berish juda muhim, ayniqsa siz oxirgi foydalanuvchilar uchun dasturiy hujjatlar yozayotgan bo'lsangiz. Foydalanuvchilarga "foydalanuvchi" o'rniga "siz" olmoshi bilan murojaat qiling.
