Dasturiy ta'minot hujjatlari shunchaki maqolalar to'plamidir. Lekin hatto ular sizni aqldan ozdirishi mumkin. Birinchidan, kerakli ko'rsatmalarni izlashga uzoq vaqt sarflaysiz. Shunda siz tushunarsiz matnni tushunasiz. Siz yozilganidek qilasiz, lekin muammo hal etilmadi. Boshqa maqola qidirasan, asabiylashasan... Bir soatdan keyin hamma narsadan voz kechasan va ketasan. Yomon hujjatlar shunday ishlaydi. Buni nima qiladi va uni qanday tuzatish kerak - kesish ostida o'qing.
Bizning eski hujjatlarimizda ko'plab kamchiliklar bor edi. Yuqorida tavsiflangan stsenariy mijozlarimizga ta'sir qilmasligi uchun biz uni deyarli bir yil davomida qayta ishlamoqdamiz. Qarang, ΠΈ .
1-muammo: tushunarsiz, yomon yozilgan maqolalar
Hujjatlarni tushunishning iloji bo'lmasa, buning nima keragi bor? Lekin hech kim ataylab tushunarsiz maqola yozmaydi. Ular muallif tomoshabinlar va maqsad haqida o'ylamasa, suv quyib, matnda xatoliklarni tekshirmasa sodir bo'ladi.
- Tomoshabin. Maqola yozishdan oldin siz o'quvchining tayyorgarlik darajasi haqida o'ylashingiz kerak. Yangi boshlanuvchilar uchun maqolada siz asosiy bosqichlarni o'tkazib yubormasligingiz va texnik atamalarni tushuntirishsiz qoldirishingiz mantiqan to'g'ri, lekin faqat professionallarga kerak bo'lgan noyob xususiyat haqidagi maqolada siz PHP so'zining ma'nosini tushuntirishingiz kerak.
- Maqsad. Oldindan o'ylash kerak bo'lgan yana bir narsa. Muallif o'z oldiga aniq maqsad qo'yishi, maqolaning foydali ta'sirini aniqlashi va uni o'qib chiqqandan keyin o'quvchi nima qilishini hal qilishi kerak. Agar bu bajarilmasa, siz tavsif uchun tavsif bilan yakunlanasiz.
- Suv va hasharotlar. Ko'p keraksiz ma'lumotlar va byurokratiya, xatolar va matn terish xatolari idrok etishga xalaqit beradi. O'quvchi grammatik nazi bo'lmasa ham, matndagi beparvolik uni o'chirib qo'yishi mumkin.
Yuqoridagi maslahatlarni ko'rib chiqing va maqolalar aniqroq bo'ladi - kafolatlangan. Buni yanada yaxshilash uchun bizning .
Muammo 2. Maqolalar barcha savollarga javob bermaydi
Hujjatlar rivojlanishga mos kelmasa, haqiqiy savollarga javob bermasa va undagi xatolar yillar davomida tuzatilmasa, bu yomon. Bular muallifning emas, balki kompaniya ichidagi jarayonlarni tashkil etishning muammolari.
Hujjatlar rivojlanishga mos kelmaydi
Funktsiya allaqachon chiqarilgan, marketing uni qamrab olishni rejalashtirmoqda, keyin esa yangi maqola yoki tarjima hali ham hujjatlarda yo'qligi ma'lum bo'ldi. Shu sababli biz hatto ozodlikni kechiktirishga majbur bo'ldik. Siz hammadan o'zingiz xohlagancha texnik yozuvchilarga vazifalarni o'z vaqtida topshirishni so'rashingiz mumkin, ammo bu ishlamaydi. Agar jarayon avtomatlashtirilmasa, vaziyat yana takrorlanadi.
YouTrack-ga o'zgartirishlar kiritdik. Yangi xususiyat haqida maqola yozish vazifasi texnik yozuvchiga xususiyat sinovdan o'ta boshlagan paytda tushadi. Keyin marketing reklamaga tayyorgarlik ko'rish uchun bu haqda bilib oladi. Bildirishnomalar Mattermost korporativ messenjeriga ham keladi, shuning uchun ishlab chiquvchilar yangiliklarini o'tkazib yuborishning iloji yo'q.
Hujjatlar foydalanuvchi so'rovlarini aks ettirmaydi
Biz shunday ishlashga odatlanganmiz: xususiyat paydo bo'ldi, biz bu haqda gaplashdik. Biz uni qanday yoqish, o'chirish va nozik sozlashlarni tasvirlab berdik. Ammo mijoz dasturimizdan biz kutmagan tarzda foydalansa-chi? Yoki unda biz o'ylamagan xatolar bormi?
Hujjatlarning iloji boricha to'liq bo'lishini ta'minlash uchun biz qo'llab-quvvatlash so'rovlarini, tematik forumlardagi savollarni va qidiruv tizimlaridagi so'rovlarni tahlil qilishni tavsiya etamiz. Eng mashhur mavzular texnik yozuvchilarga o'tkaziladi, ular mavjud maqolalarni to'ldirishlari yoki yangilarini yozishlari mumkin.
Hujjatlar takomillashtirilmayapti
Buni darhol mukammal qilish qiyin, hali ham xatolar bo'ladi. Siz mijozlarning fikr-mulohazalarini kutishingiz mumkin, ammo ular har qanday xato, noto'g'ri, tushunarsiz yoki asossiz maqola haqida xabar berishlari dargumon. Mijozlarga qo'shimcha ravishda, xodimlar hujjatlarni o'qiydilar, ya'ni ular bir xil xatolarni ko'rishadi. Bu foydalanish mumkin! Siz shunchaki muammo haqida xabar berish oson bo'ladigan sharoitlarni yaratishingiz kerak.
Bizda ichki portalda guruh mavjud bo'lib, unda xodimlar hujjatlar bo'yicha sharhlar, takliflar va g'oyalarni qoldiradilar. Qo'llab-quvvatlash uchun maqola kerakmi, lekin u mavjud emasmi? Sinovchi noaniqlikni payqadimi? Hamkor xatolar haqida rivojlanish menejerlariga shikoyat qilganmi? Hammasi shu guruhda! Texnik yozuvchilar ba'zi narsalarni darhol tuzatadi, ba'zi narsalarni YouTrack-ga o'tkazadi va boshqalarga o'ylash uchun vaqt beradi. Mavzu o'chib ketmasligi uchun vaqti-vaqti bilan guruhning mavjudligi va fikr-mulohazalarning muhimligini eslatib turamiz.
Muammo 3. To'g'ri maqolani topish uchun ko'p vaqt ketadi.
Topib bo'lmaydigan maqola topilmaydigan maqoladan yaxshiroq emas. Yaxshi hujjatlarning shiori "Qidirish oson, topish oson" bo'lishi kerak. Bunga qanday erishish mumkin?
Strukturani tashkil qilish va mavzularni tanlash tamoyilini aniqlash. O'quvchi "Ushbu maqolani qayerdan topsam bo'ladi?" deb o'ylamasligi uchun struktura iloji boricha shaffof bo'lishi kerak. Xulosa qilib aytganda, ikkita yondashuv mavjud: interfeysdan va vazifalardan.
- Interfeysdan. Kontent panel bo'limlarini takrorlaydi. Bu eski ISPsystem hujjatlarida bo'lgan.
- Vazifalardan. Maqolalar va bo'limlar sarlavhalari foydalanuvchilarning vazifalarini aks ettiradi; Sarlavhalarda deyarli har doim fe'llar va "qanday qilish kerak" degan savolga javoblar mavjud. Endi biz ushbu formatga o'tamiz.
Qaysi yondashuvni tanlamasligingizdan qat'iy nazar, mavzu foydalanuvchilar izlayotgan narsaga mos kelishiga va foydalanuvchining savoliga aniq javob beradigan tarzda yoritilganligiga ishonch hosil qiling.
Markazlashtirilgan qidiruvni o'rnating. Ideal dunyoda, siz tilni noto'g'ri yozsangiz yoki xato qilsangiz ham qidiruv ishlashi kerak. Hozircha Confluence-dagi qidiruvimiz bu bilan bizni xursand qila olmaydi. Agar sizda ko'p mahsulot bo'lsa va hujjatlar umumiy bo'lsa, qidiruvni foydalanuvchi joylashgan sahifaga moslang. Bizning holatda, asosiy sahifadagi qidiruv barcha mahsulotlar uchun ishlaydi va agar siz allaqachon ma'lum bir bo'limda bo'lsangiz, unda faqat undagi maqolalar uchun.
Tarkib va ββnon bo'laklarini qo'shing. Har bir sahifada menyu va non bo'laklari bo'lsa yaxshi bo'ladi - foydalanuvchining istalgan darajaga qaytish imkoniyati bilan joriy sahifaga yo'li. Eski ISPsystem hujjatlarida siz tarkibga kirish uchun maqoladan chiqishingiz kerak edi. Bu noqulay edi, shuning uchun biz uni yangisiga o'rnatdik.
Mahsulotga havolalarni joylashtiring. Agar odamlar bir xil savol bilan qayta-qayta qo'llab-quvvatlashga kelishsa, interfeysga uning yechimi bilan maslahat qo'shish mantiqan. Agar foydalanuvchi muammoga duch kelgani haqida ma'lumot yoki tushunchaga ega bo'lsangiz, ularni pochta ro'yxati bilan ham xabardor qilishingiz mumkin. Ularga g'amxo'rlik ko'rsating va yordam yukini olib tashlang.
Qalqib chiquvchi oynaning o'ng tomonida ISPmanager domenini boshqarish bo'limida DNSSEC-ni sozlash haqidagi maqolaga havola mavjud.
Hujjatlar ichida o'zaro havolalarni o'rnating. Bir-biri bilan bog'liq bo'lgan maqolalar "bog'langan" bo'lishi kerak. Agar maqolalar ketma-ket bo'lsa, har bir matn oxirida oldinga va orqaga o'qlarni qo'shishni unutmang.
Katta ehtimol bilan, odam o'z savoliga javob izlashga birinchi navbatda sizga emas, balki qidiruv tizimiga murojaat qiladi. Texnik sabablarga ko'ra u erda hujjatlarga havolalar bo'lmasa, bu uyat. Shunday qilib, qidiruv tizimini optimallashtirish haqida g'amxo'rlik qiling.
Muammo 4. Eskirgan tartib idrokga xalaqit beradi
Yomon matnlarga qo'shimcha ravishda, hujjatlar dizayn tomonidan buzilishi mumkin. Odamlar yaxshi yozilgan materiallarni o'qishga odatlangan. Bloglar, ijtimoiy tarmoqlar, ommaviy axborot vositalari - barcha kontent nafaqat chiroyli, balki o'qish oson va ko'zni quvontiradigan tarzda taqdim etiladi. Shuning uchun, quyidagi skrinshotdagi kabi matnni ko'rgan odamning dardini osongina tushunishingiz mumkin.
Ushbu maqolada juda ko'p skrinshotlar va diqqatga sazovor joylar mavjudki, ular yordam bermaydi, faqat idrok etishga xalaqit beradi (rasmni bosish mumkin)
Hujjatlardan ko'p effektlar bilan uzoq vaqt o'qimasligingiz kerak, lekin siz asosiy qoidalarni hisobga olishingiz kerak.
Maket. Asosiy matnning kengligi, shrift, o'lcham, sarlavhalar va to'ldirishni aniqlang. Dizaynerni yollang va ishni qabul qilish yoki o'zingiz qilish uchun Artyom Gorbunovning "Tipografiya va maket" kitobini o'qing. Bu tartibning faqat bitta ko'rinishini taqdim etadi, ammo bu juda etarli.
Ajratishlar. Matnda nimaga urg'u berish kerakligini aniqlang. Odatda bu interfeysdagi yo'l, tugmalar, kod qo'shimchalari, konfiguratsiya fayllari, "Iltimos, diqqat qiling" bloklari. Ushbu elementlarning taqsimlanishi qanday bo'lishini aniqlang va ularni qoidalarga yozib qo'ying. Shuni yodda tutingki, oqim qancha kam bo'lsa, shuncha yaxshi bo'ladi. Ular ko'p bo'lsa, matn shovqinli bo'ladi. Hatto tirnoq belgilari ham tez-tez ishlatilsa, shovqin hosil qiladi.
Skrinshotlar. Qanday hollarda skrinshotlar kerak bo'lsa, jamoa bilan kelishib oling. Albatta, har bir qadamni tasvirlashning hojati yo'q. Ko'p sonli skrinshotlar, shu jumladan. alohida tugmalar, idrokga xalaqit beradi, tartibni buzadi. Skrinshotlardagi diqqatga sazovor joylar va imzolarning hajmini, shuningdek formatini aniqlang va ularni reglamentga yozing. Esda tutingki, rasmlar har doim yozilganlarga mos kelishi va tegishli bo'lishi kerak. Shunga qaramay, agar mahsulot muntazam ravishda yangilanib tursa, hammani kuzatib borish qiyin bo'ladi.
Matn uzunligi. Haddan tashqari uzun maqolalardan saqlaning. Ularni qismlarga bo'ling va agar buning iloji bo'lmasa, maqolaning boshiga langar havolalari bilan tarkib qo'shing. Maqolani vizual ravishda qisqartirishning oddiy usuli - bu tor doiradagi o'quvchilar uchun zarur bo'lgan texnik tafsilotlarni spoyler ostida yashirishdir.
Formatlar. Maqolalaringizda bir nechta formatlarni birlashtiring: matn, video va rasmlar. Bu idrokni yaxshilaydi.
Chiroyli tartib bilan muammolarni yashirishga urinmang. Rostini aytsam, biz o'zimiz ham "o'rash" eskirgan hujjatlarni saqlab qolishiga umid qilgan edik - bu ish bermadi. Matnlar shunchalik ko'p vizual shovqin va keraksiz tafsilotlarni o'z ichiga olganki, qoidalar va yangi dizayn kuchsiz edi.
Yuqoridagilarning aksariyati siz hujjatlar uchun foydalanadigan platforma tomonidan aniqlanadi. Masalan, bizda Confluence bor. Men ham u bilan shug'ullanishim kerak edi. Agar qiziqsangiz, bizning veb-ishlab chiquvchimizning hikoyasini o'qing: .
Yaxshilashni qaerdan boshlash kerak va qanday qilib omon qolish kerak
Agar sizning hujjatlaringiz provayder tizimidagidek keng bo'lsa va qaerdan boshlashni bilmasangiz, eng katta muammolardan boshlang. Mijozlar hujjatni tushunmaydilar - matnlarni takomillashtirish, qoidalarni ishlab chiqish, yozuvchilarni tayyorlash. Hujjatlar eskirgan - ichki jarayonlarga g'amxo'rlik qiling. Eng mashhur mahsulotlar haqidagi eng mashhur maqolalardan boshlang: yordam so'rang, sayt tahlillari va qidiruv tizimlaridagi so'rovlarga qarang.
Darhol aytaylik - bu oson bo'lmaydi. Va bu ham tez ishlashi dargumon. Agar siz endigina ish boshlamasangiz va darhol to'g'ri ish qilmasangiz. Bir narsani aniq bilamizki, vaqt o'tishi bilan yaxshilanadi. Ammo jarayon hech qachon tugamaydi :-).
Manba: www.habr.com