वापरकर्ता दस्तऐवजीकरण: ते काय खराब करते आणि त्याचे निराकरण कसे करावे

सॉफ्टवेअर दस्तऐवजीकरण हे फक्त लेखांचा संच आहे. पण तरीही ते तुम्हाला वेड लावू शकतात. प्रथम, आपण आवश्यक सूचना शोधण्यात बराच वेळ घालवला. मग तुम्हाला अस्पष्ट मजकूर समजेल. तुम्ही लिहिल्याप्रमाणे करा, पण समस्या सुटत नाही. तुम्ही दुसरा लेख शोधता, तुम्ही घाबरून जाता... एक तासानंतर तुम्ही सर्व काही सोडून देता आणि निघून जाता. अशा प्रकारे खराब दस्तऐवजीकरण कार्य करते. हे असे काय बनवते आणि त्याचे निराकरण कसे करावे - कट अंतर्गत वाचा.

आमच्या जुन्या कागदपत्रांमध्ये अनेक त्रुटी होत्या. वर वर्णन केलेल्या परिस्थितीचा आमच्या क्लायंटवर परिणाम होऊ नये म्हणून आम्ही आता जवळजवळ एक वर्षापासून ते पुन्हा काम करत आहोत. दिसत, जसे होते तसे и हे कसे घडले.

समस्या 1: अस्पष्ट, खराब लिहिलेले लेख

जर कागदपत्रे समजणे अशक्य असेल तर त्यात काय अर्थ आहे? पण हेतुपुरस्सर अनाकलनीय लेख कोणीही लिहित नाही. जेव्हा लेखक प्रेक्षक आणि हेतूबद्दल विचार करत नाही, पाणी ओततो आणि त्रुटींसाठी मजकूर तपासत नाही तेव्हा ते घडतात.

• प्रेक्षक. लेख लिहिण्यापूर्वी, तुम्हाला वाचकांच्या तयारीच्या पातळीबद्दल विचार करणे आवश्यक आहे. हे तर्कसंगत आहे की नवशिक्यासाठीच्या लेखात तुम्ही मूलभूत पायऱ्या वगळू नये आणि स्पष्टीकरणाशिवाय तांत्रिक संज्ञा सोडू नये, परंतु केवळ व्यावसायिकांना आवश्यक असलेल्या दुर्मिळ वैशिष्ट्यावरील लेखात, तुम्ही PHP शब्दाचा अर्थ स्पष्ट केला पाहिजे.
• गोल. आगाऊ विचार करण्यासाठी आणखी एक गोष्ट. लेखकाने स्पष्ट ध्येय निश्चित केले पाहिजे, लेखाचा उपयुक्त परिणाम निश्चित केला पाहिजे आणि तो वाचल्यानंतर वाचक काय करेल हे ठरवावे. हे केले नाही तर, आपण वर्णन फायद्यासाठी वर्णन सह समाप्त होईल.
• पाणी आणि बग. बरीच अनावश्यक माहिती आहे आणि नोकरशाही, चुका आणि टायपॉस समजण्यात हस्तक्षेप करतात. जरी वाचक व्याकरणाचा नाझी नसला तरी मजकूरातील निष्काळजीपणा त्याला बंद करू शकतो.

वरील टिप्स विचारात घ्या, आणि लेख अधिक स्पष्ट होतील - हमी. ते आणखी चांगले करण्यासाठी, आमचा वापर करा तांत्रिक कागदपत्रांवर काम करताना 50 प्रश्न.

समस्या 2. लेख सर्व प्रश्नांची उत्तरे देत नाहीत

जेव्हा दस्तऐवजीकरण विकासाबरोबर राहत नाही, वास्तविक प्रश्नांची उत्तरे देत नाही आणि त्यातील त्रुटी वर्षानुवर्षे दुरुस्त केल्या जात नाहीत तेव्हा हे वाईट आहे. या समस्या लेखकाच्या नसून कंपनीतील प्रक्रियांच्या संघटनेच्या आहेत.

दस्तऐवजीकरण विकासासोबत ठेवत नाही

वैशिष्ट्य आधीच रिलीजमध्ये आहे, विपणन योजना ते कव्हर करण्यासाठी, आणि नंतर असे दिसून आले की नवीन लेख किंवा भाषांतर अद्याप दस्तऐवजीकरणात नाही. यामुळे आम्हाला रिलीजही पुढे ढकलावे लागले. तुम्हाला पाहिजे तितक्या वेळेवर तांत्रिक लेखकांना कार्ये सोपवण्यास तुम्ही प्रत्येकाला सांगू शकता, परंतु ते कार्य करणार नाही. प्रक्रिया स्वयंचलित नसल्यास, परिस्थिती स्वतःच पुनरावृत्ती होईल.

आम्ही YouTrack मध्ये बदल केले आहेत. नवीन वैशिष्ट्याबद्दल लेख लिहिण्याचे काम जेव्हा वैशिष्ट्याची चाचणी सुरू होते त्याच क्षणी तांत्रिक लेखकाकडे येते. मग प्रमोशनची तयारी करण्यासाठी मार्केटिंग त्याबद्दल शिकते. नोटिफिकेशन्स मॅटरमोस्ट कॉर्पोरेट मेसेंजरवर देखील येतात, त्यामुळे डेव्हलपरकडून बातम्या चुकणे अशक्य आहे.

दस्तऐवजीकरण वापरकर्त्याच्या विनंत्या प्रतिबिंबित करत नाही

आम्हाला असे काम करण्याची सवय आहे: एक वैशिष्ट्य बाहेर आले, आम्ही त्याबद्दल बोललो. आम्ही ते कसे चालू करावे, ते कसे बंद करावे आणि बारीक समायोजन कसे करावे याचे वर्णन केले आहे. पण जर एखाद्या क्लायंटने आमचे सॉफ्टवेअर अशा प्रकारे वापरले तर ज्याची आम्हाला अपेक्षा नव्हती? किंवा त्यात काही त्रुटी आहेत ज्यांचा आम्ही विचार केला नाही?

दस्तऐवजीकरण शक्य तितके पूर्ण आहे याची खात्री करण्यासाठी, आम्ही समर्थन विनंत्या, थीमॅटिक फोरमवरील प्रश्न आणि शोध इंजिनमधील प्रश्नांचे विश्लेषण करण्याची शिफारस करतो. सर्वात लोकप्रिय विषय तांत्रिक लेखकांना हस्तांतरित केले जातील जेणेकरून ते विद्यमान लेखांना पूरक किंवा नवीन लिहू शकतील.

दस्तऐवजीकरण सुधारले जात नाही

ते लगेच करणे कठीण आहे; तरीही चुका होतील. तुम्ही ग्राहकांकडून फीडबॅकची आशा करू शकता, परंतु ते प्रत्येक टायपिंग, चुकीची, न समजण्याजोगी किंवा चुकीच्या लेखाची तक्रार करतील अशी शक्यता नाही. क्लायंट व्यतिरिक्त, कर्मचारी कागदपत्रे वाचतात, याचा अर्थ त्यांना समान त्रुटी दिसतात. हे वापरले जाऊ शकते! तुम्हाला फक्त अशा परिस्थिती निर्माण करण्याची आवश्यकता आहे ज्यामध्ये समस्या नोंदवणे सोपे होईल.

आमच्याकडे अंतर्गत पोर्टलवर एक गट आहे जेथे कर्मचारी दस्तऐवजीकरणावर टिप्पण्या, सूचना आणि कल्पना देतात. समर्थनासाठी लेख आवश्यक आहे, परंतु तो अस्तित्वात नाही? परीक्षकाला चुकीची बाब लक्षात आली का? भागीदाराने विकास व्यवस्थापकांकडे त्रुटींबद्दल तक्रार केली आहे का? या गटातील सर्व! तांत्रिक लेखक काही गोष्टी लगेच दुरुस्त करतात, काही गोष्टी YouTrack वर हस्तांतरित करतात आणि इतरांना विचार करण्यासाठी थोडा वेळ देतात. विषय संपुष्टात येण्यापासून रोखण्यासाठी, आम्ही वेळोवेळी तुम्हाला ग्रुपचे अस्तित्व आणि फीडबॅकचे महत्त्व याची आठवण करून देतो.

समस्या 3. योग्य लेख शोधण्यासाठी बराच वेळ लागतो.

सापडत नाही असा लेख सापडत नसलेल्या लेखापेक्षा चांगला नाही. चांगल्या दस्तऐवजीकरणाचे ब्रीदवाक्य "शोधण्यास सोपे, शोधण्यास सोपे" असावे. हे कसे साध्य करायचे?

रचना व्यवस्थित करा आणि विषय निवडण्यासाठी तत्त्व निश्चित करा. रचना शक्य तितकी पारदर्शक असावी जेणेकरून वाचकाला असे वाटणार नाही की "मला हा लेख कुठे मिळेल?" थोडक्यात, दोन पध्दती आहेत: इंटरफेस आणि कार्यांमधून.

1. इंटरफेस पासून. सामग्री पॅनेल विभागांची डुप्लिकेट करते. जुन्या ISPsystem दस्तऐवजात हे प्रकरण होते.
2. कार्यांमधून. लेख आणि विभागांची शीर्षके वापरकर्त्यांची कार्ये प्रतिबिंबित करतात; शीर्षकांमध्ये जवळजवळ नेहमीच क्रियापद आणि "कसे करावे" प्रश्नाची उत्तरे असतात. आता आपण या स्वरूपाकडे जात आहोत.

तुम्ही कोणताही दृष्टीकोन निवडता, हे सुनिश्चित करा की विषय वापरकर्ते काय शोधत आहेत याच्याशी संबंधित आहे आणि वापरकर्त्याच्या प्रश्नाला विशेषत: संबोधित करेल अशा प्रकारे कव्हर केले आहे.

केंद्रीकृत शोध सेट करा. आदर्श जगात, तुम्ही चुकीचे शब्दलेखन करता किंवा भाषेत चूक केली तरीही शोध कार्य करेल. संगमातील आमचा आतापर्यंतचा शोध यामुळे आम्हाला संतुष्ट करू शकत नाही. तुमच्याकडे अनेक उत्पादने असल्यास आणि दस्तऐवजीकरण सामान्य असल्यास, वापरकर्ता ज्या पृष्ठावर आहे त्या पृष्ठासाठी शोध तयार करा. आमच्या बाबतीत, मुख्य पृष्ठावरील शोध सर्व उत्पादनांसाठी कार्य करते आणि जर तुम्ही आधीपासून विशिष्ट विभागात असाल तर फक्त त्यातील लेखांसाठी.

सामग्री आणि ब्रेडक्रंब जोडा. जेव्हा प्रत्येक पृष्ठावर मेनू आणि ब्रेडक्रंब असतात तेव्हा ते चांगले असते - कोणत्याही स्तरावर परत येण्याच्या क्षमतेसह वापरकर्त्याचा वर्तमान पृष्ठाचा मार्ग. जुन्या ISPsystem दस्तऐवजीकरणामध्ये, तुम्हाला सामग्री मिळवण्यासाठी लेखातून बाहेर पडावे लागले. ते गैरसोयीचे होते, म्हणून आम्ही ते नवीनमध्ये निश्चित केले.

उत्पादनामध्ये दुवे ठेवा. जर लोक त्याच प्रश्नाचे समर्थन करण्यासाठी वारंवार येत असतील तर, इंटरफेसमध्ये त्याच्या समाधानासह एक इशारा जोडण्यात अर्थ आहे. जर तुमच्याकडे डेटा किंवा अंतर्दृष्टी असेल जेव्हा वापरकर्त्याला समस्या येत असेल तर तुम्ही त्यांना मेलिंग सूचीसह सूचित देखील करू शकता. त्यांना काळजी दाखवा आणि समर्थनाचे ओझे काढून टाका.

पॉप-अप विंडोमध्ये उजवीकडे ISPmanager च्या डोमेन व्यवस्थापन विभागात DNSSEC सेट करण्याबद्दलच्या लेखाची लिंक आहे

दस्तऐवजीकरणामध्ये क्रॉस-रेफरन्स सेट करा. एकमेकांशी संबंधित लेख "लिंक केलेले" असावेत. लेख अनुक्रमिक असल्यास, प्रत्येक मजकुराच्या शेवटी पुढे आणि मागे बाण जोडण्याची खात्री करा.

बहुधा, एखादी व्यक्ती प्रथम आपल्या प्रश्नाचे उत्तर शोधत नाही तर शोध इंजिनकडे जाईल. तांत्रिक कारणास्तव तेथे दस्तऐवजीकरणाचे कोणतेही दुवे नसल्यास ही लाजिरवाणी गोष्ट आहे. त्यामुळे सर्च इंजिन ऑप्टिमायझेशनची काळजी घ्या.

समस्या 4. कालबाह्य लेआउट समज मध्ये हस्तक्षेप करते

खराब मजकूर व्यतिरिक्त, दस्तऐवजीकरण डिझाइनद्वारे खराब केले जाऊ शकते. लोकांना चांगले लिहिलेले साहित्य वाचण्याची सवय आहे. ब्लॉग, सोशल नेटवर्क्स, मीडिया - सर्व सामग्री केवळ सुंदरच नाही तर डोळ्यांना वाचण्यास सोपी आणि आनंददायक देखील सादर केली जाते. त्यामुळे, खाली दिलेल्या स्क्रीनशॉटप्रमाणे मजकूर पाहणाऱ्या व्यक्तीचे दुःख तुम्ही सहज समजू शकता.

या लेखात इतके स्क्रीनशॉट आणि हायलाइट्स आहेत की ते मदत करत नाहीत, परंतु केवळ आकलनात हस्तक्षेप करतात (चित्र क्लिक करण्यायोग्य आहे)

आपण अनेक प्रभावांसह दस्तऐवजातून दीर्घ वाचन करू नये, परंतु आपल्याला मूलभूत नियम विचारात घेणे आवश्यक आहे.

मांडणी. मुख्य मजकूर रुंदी, फॉन्ट, आकार, शीर्षके आणि पॅडिंग निश्चित करा. एका डिझायनरची नियुक्ती करा आणि काम स्वीकारण्यासाठी किंवा ते स्वतः करण्यासाठी, आर्टिओम गोर्बुनोव्हचे "टायपोग्राफी आणि लेआउट" हे पुस्तक वाचा. हे लेआउटचे फक्त एक दृश्य सादर करते, परंतु ते पुरेसे आहे.

वाटप. मजकूरात कशावर जोर देणे आवश्यक आहे ते ठरवा. सामान्यत: हा इंटरफेस, बटणे, कोड इन्सर्ट, कॉन्फिगरेशन फाइल्स, "कृपया लक्षात ठेवा" ब्लॉक्समधील एक मार्ग आहे. या घटकांचे वाटप काय असेल ते ठरवा आणि ते नियमांमध्ये नोंदवा. लक्षात ठेवा की कमी डिस्चार्ज, चांगले. जेव्हा ते बरेच असतात तेव्हा मजकूर गोंगाट करणारा असतो. जरी अवतरण चिन्हे खूप वेळा वापरली तर आवाज निर्माण करतात.

स्क्रिनशॉट्स. कोणत्या प्रकरणांमध्ये स्क्रीनशॉट आवश्यक आहेत त्या टीमशी सहमत व्हा. प्रत्येक पायरीचे उदाहरण देण्याची गरज नक्कीच नाही. मोठ्या संख्येने स्क्रीनशॉट, समावेश. विभक्त बटणे, आकलनात व्यत्यय आणणे, लेआउट खराब करणे. आकार, तसेच स्क्रीनशॉट्सवरील हायलाइट्स आणि स्वाक्षरींचे स्वरूप निश्चित करा आणि ते नियमांमध्ये रेकॉर्ड करा. लक्षात ठेवा की चित्रे नेहमी लिहिलेल्या गोष्टींशी सुसंगत आणि संबंधित असावीत. पुन्हा, उत्पादन नियमितपणे अद्यतनित केले असल्यास, प्रत्येकाचा मागोवा ठेवणे कठीण होईल.

मजकूर लांबी. जास्त लांब लेख टाळा. त्यांना भागांमध्ये विभाजित करा आणि हे शक्य नसल्यास, लेखाच्या सुरूवातीस अँकर लिंकसह सामग्री जोडा. लेख दृष्यदृष्ट्या लहान करण्याचा एक सोपा मार्ग म्हणजे वाचकांच्या एका अरुंद वर्तुळासाठी आवश्यक तांत्रिक तपशील स्पॉयलरच्या खाली लपवणे.

स्वरूप. तुमच्या लेखांमध्ये अनेक स्वरूपे एकत्र करा: मजकूर, व्हिडिओ आणि प्रतिमा. हे समज सुधारेल.

सुंदर मांडणीसह समस्या लपविण्याचा प्रयत्न करू नका. प्रामाणिकपणे, आम्हाला आशा होती की "रॅपर" कालबाह्य कागदपत्रे जतन करेल - ते कार्य करत नाही. मजकुरात इतका व्हिज्युअल आवाज आणि अनावश्यक तपशील होते की नियम आणि नवीन डिझाइन शक्तीहीन होते.

वरीलपैकी बरेच काही तुम्ही दस्तऐवजीकरणासाठी वापरत असलेल्या प्लॅटफॉर्मद्वारे निर्धारित केले जाईल. उदाहरणार्थ, आपल्याकडे संगम आहे. मलाही त्याच्याशी टिंगल करावी लागली. स्वारस्य असल्यास, आमच्या वेब विकसकाची कथा वाचा: सार्वजनिक ज्ञान बेससाठी संगम: रचना बदलणे आणि भाषांद्वारे वेगळे करणे.

कुठे सुधारणा करायला सुरुवात करायची आणि कसे टिकायचे

तुमचे दस्तऐवज ISPsystem इतकेच विस्तीर्ण असल्यास आणि तुम्हाला कुठून सुरुवात करावी हे माहित नसेल, तर सर्वात मोठ्या समस्यांपासून सुरुवात करा. क्लायंटला दस्तऐवज समजत नाही - मजकूर सुधारा, नियम बनवा, लेखकांना प्रशिक्षण द्या. दस्तऐवजीकरण कालबाह्य झाले आहे - अंतर्गत प्रक्रियांची काळजी घ्या. सर्वात लोकप्रिय उत्पादनांबद्दल सर्वात लोकप्रिय लेखांसह प्रारंभ करा: समर्थन विचारा, शोध इंजिनमधील साइट विश्लेषणे आणि क्वेरी पहा.

चला लगेच म्हणूया - हे सोपे होणार नाही. आणि ते त्वरीत कार्य करण्याची शक्यता नाही. जोपर्यंत तुम्ही आत्ताच सुरुवात करत नाही आणि लगेच योग्य गोष्ट करत नाही. एक गोष्ट आपल्याला निश्चितपणे माहित आहे की ती कालांतराने अधिक चांगली होईल. पण प्रक्रिया कधीच संपणार नाही :-).

स्त्रोत: www.habr.com