Бағдарламалық қамтамасыз ету құжаттамасы мақалалар жиынтығы ғана. Бірақ тіпті олар сізді ақылсыз ете алады. Біріншіден, сіз қажетті нұсқауларды іздеуге ұзақ уақыт жұмсайсыз. Сонда сіз түсініксіз мәтінді түсінесіз. Сіз жазғандай жасайсыз, бірақ мәселе шешілмейді. Басқа мақала іздейсің, қобалжисың... Бір сағаттан соң бәрін тастап кетесің. Нашар құжаттама осылай жұмыс істейді. Нені осылай жасайды және оны қалай түзетуге болады - кесу астында оқыңыз.
Ескі құжаттамамызда олқылықтар көп болды. Жоғарыда сипатталған сценарий біздің клиенттерімізге әсер етпеуі үшін біз оны бір жылға жуық уақыт бойы қайта өңдеп жатырмыз. Қараңыз, и .
1-мәселе: Түсініксіз, нашар жазылған мақалалар
Егер құжаттаманы түсіну мүмкін болмаса, оның мәні неде? Бірақ ешкім әдейі түсініксіз мақалалар жазбайды. Олар автор аудитория мен мақсат туралы ойланбай, су құйып, мәтінде қате бар-жоғын тексермегенде болады.
- Көрермендер. Мақала жазбас бұрын оқырманның дайындық деңгейі туралы ойлану керек. Жаңадан бастаушыларға арналған мақалада негізгі қадамдарды өткізіп жіберіп, техникалық терминдерді түсіндірместен қалдыруға болмайды, бірақ тек кәсіпқойларға қажет сирек мүмкіндік туралы мақалада PHP сөзінің мағынасын түсіндіру керек.
- Максат. Алдын ала ойланатын тағы бір нәрсе. Автор нақты мақсат қойып, мақаланың пайдалы әсерін анықтауы керек және оны оқығаннан кейін оқырман не істейтінін шешуі керек. Егер бұл жасалмаса, сіз сипаттау үшін сипаттамамен аяқталасыз.
- Су және қателер. Көптеген қажетсіз ақпараттар мен бюрократизм, қателер мен қателер қабылдауға кедергі келтіреді. Оқырман грамматикалық нацист болмаса да, мәтіндегі немқұрайлылық оны өшіруі мүмкін.
Жоғарыдағы кеңестерді қарастырыңыз, сонда мақалалар анық болады - кепілдік беріледі. Оны одан да жақсырақ ету үшін біздің .
Мәселе 2. Мақалалар барлық сұрақтарға жауап бермейді
Құжаттама дамуға ілеспесе, нақты сұрақтарға жауап бермесе және ондағы қателер жылдар бойы түзетілмесе, бұл жаман. Бұл автордың емес, компания ішіндегі процестерді ұйымдастырудың мәселелері.
Құжаттама дамуға ілеспейді
Мүмкіндік қазірдің өзінде шығарылымда, маркетинг оны қамтуды жоспарлап отыр, содан кейін жаңа мақала немесе аударма әлі де құжаттамада жоқ екені белгілі болды. Осыған байланысты босатуды кейінге қалдыруға да тура келді. Сіз барлығынан техникалық жазушыларға тапсырмаларды қалағаныңызша уақытында тапсыруды сұрай аласыз, бірақ ол жұмыс істемейді. Егер процесс автоматтандырылмаса, жағдай қайталанады.
YouTrack-ке өзгерістер енгіздік. Жаңа мүмкіндік туралы мақала жазу міндеті техникалық жазушыға мүмкіндік сынала бастаған сәтте түседі. Содан кейін маркетинг ілгерілетуге дайындалу үшін бұл туралы біледі. Хабарландырулар Mattermost корпоративтік мессенджеріне де келеді, сондықтан әзірлеушілерден жаңалықтарды жіберіп алу мүмкін емес.
Құжаттама пайдаланушы сұрауларын көрсетпейді
Біз осылай жұмыс істеуге үйреніп қалдық: бір функция шықты, біз бұл туралы сөйлестік. Біз оны қосу, өшіру және жақсы реттеулер жасау жолын сипаттадық. Бірақ клиент бағдарламалық жасақтаманы біз күтпегендей пайдаланса ше? Әлде оның біз ойламаған қателері бар ма?
Құжаттаманың мүмкіндігінше толық болуын қамтамасыз ету үшін қолдау сұрауларын, тақырыптық форумдардағы сұрақтарды және іздеу жүйелеріндегі сұрауларды талдауды ұсынамыз. Ең танымал тақырыптар бұрыннан бар мақалаларды толықтыру немесе жаңа мақалалар жазу үшін техникалық жазушыларға беріледі.
Құжаттар жетілдірілмейді
Мұны бірден мінсіз орындау қиын, қателіктер әлі де болады. Клиенттерден кері байланыс күтуге болады, бірақ олардың әрбір қате, дәлсіздік, түсініксіз немесе негізсіз мақала туралы хабарлауы екіталай. Клиенттерден басқа, қызметкерлер құжаттаманы оқиды, яғни олар бірдей қателерді көреді. Мұны қолдануға болады! Сізге мәселе туралы хабарлау оңай болатындай жағдай жасау керек.
Бізде ішкі порталда қызметкерлер құжаттамаға қатысты ескертулер, ұсыныстар мен идеялар қалдыратын топ бар. Қолдау көрсетуге мақала керек пе, бірақ ол жоқ па? Тестілеуші дәлсіздікті байқады ма? Серіктес даму менеджерлеріне қателер туралы шағымданды ма? Барлығы осы топта! Техникалық жазушылар кейбір нәрселерді бірден түзетеді, кейбір нәрселерді YouTrack-ке тасымалдайды және басқаларға ойлануға уақыт береді. Тақырып өліп қалмас үшін, біз мезгіл-мезгіл топтың бар екенін және кері байланыс маңыздылығын еске саламыз.
Мәселе 3. Дұрыс мақаланы табу үшін көп уақыт қажет.
Табылмайтын мақаладан табылмайтын мақала артық емес. Жақсы құжаттаманың ұраны «Іздеуге оңай, табу оңай» болуы керек. Бұған қалай қол жеткізуге болады?
Құрылымды жүйелеу және тақырыптарды таңдау принципін анықтау. Оқырман «Бұл мақаланы қайдан таба аламын?» деп ойламауы үшін құрылым мүмкіндігінше ашық болуы керек. Қорытындылай келе, екі тәсіл бар: интерфейстен және тапсырмалардан.
- Интерфейстен. Мазмұн панель бөлімдерін қайталайды. Бұл ескі ISPsystem құжаттамасында болған.
- Тапсырмалардан. Мақалалар мен бөлімдердің атаулары пайдаланушылардың міндеттерін көрсетеді; Тақырыптарда әрдайым дерлік етістіктер және «қалай» деген сұраққа жауаптар болады. Енді осы форматқа көшеміз.
Қандай тәсілді таңдасаңыз да, тақырыптың пайдаланушылар іздеген нәрсеге сәйкес келетініне және пайдаланушының сұрағына арнайы жауап беретін жолмен қамтылғанына көз жеткізіңіз.
Орталықтандырылған іздеуді орнатыңыз. Идеалды әлемде қате жазғанда немесе тілде қателескен кезде де іздеу жұмыс істеуі керек. Біздің Конфлуенстегі іздестіруіміз бізді бұған қуанта алмайды. Егер сізде көптеген өнімдер болса және құжаттама жалпы болса, іздеуді пайдаланушы бар бетке бейімдеңіз. Біздің жағдайда негізгі бетте іздеу барлық өнімдер үшін жұмыс істейді, ал егер сіз белгілі бір бөлімде болсаңыз, онда тек ондағы мақалалар үшін.
Мазмұн мен нан үгінділерін қосыңыз. Әрбір бетте мәзір мен нан үгінділері болған кезде жақсы - пайдаланушының кез келген деңгейге оралу мүмкіндігі бар ағымдағы бетке жолы. Ескі ISPsystem құжаттамасында мазмұнға өту үшін мақаладан шығу керек болды. Бұл ыңғайсыз болды, сондықтан оны жаңасына жөндедік.
Сілтемелерді өнімге орналастырыңыз. Егер адамдар бір сұрақпен қайта-қайта қолдау көрсетуге келсе, интерфейске оның шешімімен кеңес қосудың мағынасы бар. Егер сізде деректер немесе пайдаланушы мәселеге кезігетін түсінік болса, оларды тарату тізімімен де хабарлауға болады. Оларға қамқорлық көрсетіңіз және қолдаудың ауыртпалығын алыңыз.
Қалқымалы терезенің оң жағында ISPmanager доменін басқару бөлімінде DNSSEC орнату туралы мақалаға сілтеме бар.
Құжаттамада айқас сілтемелерді орнатыңыз. Бір-бірімен байланысты мақалалар «байланысты» болуы керек. Егер мақалалар ретті болса, әр мәтіннің соңына алға және артқа көрсеткілерді қосуды ұмытпаңыз.
Сірә, адам алдымен өз сұрағына жауап іздеуге сізге емес, іздеу жүйесіне барады. Техникалық себептерге байланысты құжаттамаға сілтемелер болмаса, бұл ұят. Сондықтан іздеу жүйесін оңтайландыру туралы қамқорлық жасаңыз.
Мәселе 4. Ескірген макет қабылдауға кедергі келтіреді
Нашар мәтіндерден басқа, құжаттама дизайнмен бұзылуы мүмкін. Адамдар жақсы жазылған материалдарды оқуға дағдыланған. Блогтар, әлеуметтік желілер, БАҚ - барлық мазмұн әдемі ғана емес, сонымен қатар оқуға оңай және көзге ұнамды түрде ұсынылған. Сондықтан төмендегі скриншоттағыдай мәтінді көрген адамның ауырсынуын оңай түсінуге болады.
Бұл мақалада скриншоттар мен маңызды сәттердің көптігі сонша, олар көмектеспейді, бірақ қабылдауға кедергі келтіреді (суретті басуға болады)
Көптеген әсерлері бар құжаттамадан ұзақ оқуға болмайды, бірақ негізгі ережелерді ескеру қажет.
Орналасу. Негізгі мәтіннің енін, қаріпті, өлшемін, тақырыптарын және толтыруды анықтаңыз. Дизайнерді жалдаңыз және жұмысты қабылдау немесе өзіңіз жасау үшін Артём Горбуновтың «Типография және макет» кітабын оқыңыз. Ол макеттің бір ғана көрінісін ұсынады, бірақ бұл жеткілікті.
Бөліну. Мәтінде не нәрсеге баса назар аудару керектігін анықтаңыз. Әдетте бұл интерфейстегі жол, түймелер, код кірістірулері, конфигурация файлдары, «Назар аударыңыз» блоктары. Бұл элементтердің бөлінуі қандай болатынын анықтаңыз және оларды нормативтік құжаттарға жазыңыз. Неғұрлым аз разряд болса, соғұрлым жақсы екенін есте сақтаңыз. Олар көп болғанда, мәтін шулы болады. Тырнақшалар тым жиі қолданылса, шу шығарады.
Скриншоты. Қандай жағдайларда скриншоттар қажет болатынын командамен келісіңіз. Әрбір қадамды суреттеудің қажеті жоқ. Скриншоттардың үлкен саны, соның ішінде. бөлек түймелер, қабылдауға кедергі келтіреді, орналасуды бұзады. Өлшемді, сондай-ақ скриншоттардағы ерекшеліктер мен қолтаңбалардың пішімін анықтаңыз және оларды нормативтік құжаттарға жазыңыз. Есіңізде болсын, иллюстрациялар әрқашан жазылғанға сәйкес және өзекті болуы керек. Тағы да, егер өнім үнемі жаңартылса, барлығын қадағалау қиын болады.
Мәтін ұзындығы. Тым ұзақ мақалалардан аулақ болыңыз. Оларды бөліктерге бөліңіз, егер бұл мүмкін болмаса, мақаланың басына анкерлік сілтемелері бар мазмұнды қосыңыз. Мақаланы көрнекі түрде қысқартудың қарапайым тәсілі - оқырмандардың тар шеңберіне қажет техникалық мәліметтерді спойлердің астына жасыру.
Пішіндер. Мақалаларыңызда бірнеше форматты біріктіріңіз: мәтін, бейне және суреттер. Бұл қабылдауды жақсартады.
Әдемі орналасумен проблемаларды жабуға тырыспаңыз. Шынымды айтсам, біз «қаптама» ескірген құжаттаманы сақтайды деп үміттендік - бұл нәтиже бермеді. Мәтіндерде визуалды шу мен қажетсіз мәліметтер болғаны сонша, ережелер мен жаңа дизайн күшсіз болды.
Жоғарыда айтылғандардың көпшілігі құжаттама үшін пайдаланатын платформамен анықталады. Мысалы, бізде Confluence бар. Мен де онымен араласуға тура келді. Қызық болса, біздің веб-әзірлеушіміздің тарихын оқыңыз: .
Жақсартуды қайдан бастау керек және қалай аман қалу керек
Егер сіздің құжаттамаңыз ISP жүйесіндегідей ауқымды болса және сіз неден бастау керектігін білмесеңіз, ең үлкен мәселелерден бастаңыз. Клиенттер құжатты түсінбейді - мәтіндерді жетілдіреді, ережелер жасайды, жазушыларды оқытады. Құжаттама ескірген - ішкі процестерге қамқорлық жасаңыз. Ең танымал өнімдер туралы ең танымал мақалалардан бастаңыз: қолдау сұраңыз, сайт талдаулары мен іздеу жүйелеріндегі сұрауларды қараңыз.
Бірден айтайық - бұл оңай болмайды. Оның да тез жұмыс істеуі екіталай. Егер сіз жаңадан бастаған болсаңыз және бірден дұрыс нәрсені жасасаңыз. Бір анық білетініміз, уақыт өте келе жақсарады. Бірақ процесс ешқашан аяқталмайды :-).
Ақпарат көзі: www.habr.com