उपयोगकर्ता दस्तावेज़: इसे क्या ख़राब बनाता है और इसे कैसे ठीक किया जाए

सॉफ़्टवेयर दस्तावेज़ीकरण केवल लेखों का एक सेट है। लेकिन फिर भी वे आपको पागल कर सकते हैं। सबसे पहले, आप आवश्यक निर्देशों की तलाश में लंबा समय बिताते हैं। तब आप अस्पष्ट पाठ को समझ पाते हैं। आप जैसा लिखा है वैसा ही करते हैं, लेकिन समस्या का समाधान नहीं होता। आप दूसरे लेख की तलाश करते हैं, आप घबरा जाते हैं... एक घंटे बाद आप सब कुछ छोड़ देते हैं और चले जाते हैं। ख़राब दस्तावेज़ीकरण इसी प्रकार काम करता है. इसे ऐसा क्या बनाता है और इसे कैसे ठीक किया जाए - कट के नीचे पढ़ें।

हमारे पुराने दस्तावेज में कई कमियां थीं. हम लगभग एक साल से इस पर दोबारा काम कर रहे हैं ताकि ऊपर वर्णित परिदृश्य हमारे ग्राहकों को प्रभावित न करे। देखना, जैसा था и यह कैसे हुआ.

समस्या 1: अस्पष्ट, ख़राब तरीके से लिखे गए लेख

यदि दस्तावेज़ को समझना असंभव है, तो इसका मतलब क्या है? लेकिन कोई भी जानबूझकर समझ से परे लेख नहीं लिखता। वे तब होते हैं जब लेखक दर्शकों और उद्देश्य के बारे में नहीं सोचता, पानी डालता है और त्रुटियों के लिए पाठ की जाँच नहीं करता है।

• दर्शक. लेख लिखने से पहले आपको पाठक की तैयारी के स्तर के बारे में सोचना होगा। यह तर्कसंगत है कि एक शुरुआती व्यक्ति के लिए एक लेख में आपको बुनियादी चरणों को नहीं छोड़ना चाहिए और तकनीकी शब्दों को बिना स्पष्टीकरण के नहीं छोड़ना चाहिए, लेकिन एक दुर्लभ विशेषता पर एक लेख में जिसकी केवल पेशेवरों को आवश्यकता होती है, आपको PHP शब्द का अर्थ समझाना चाहिए।
• लक्ष्य. एक और बात पहले से सोच लेनी चाहिए. लेखक को एक स्पष्ट लक्ष्य निर्धारित करना चाहिए, लेख के उपयोगी प्रभाव को निर्धारित करना चाहिए और यह तय करना चाहिए कि पाठक इसे पढ़ने के बाद क्या करेगा। यदि ऐसा नहीं किया जाता है, तो आप विवरण के लिए विवरण के साथ समाप्त हो जायेंगे।
• पानी और कीड़े. बहुत सारी अनावश्यक जानकारी है और नौकरशाही, त्रुटियां और टाइपो त्रुटियां धारणा में बाधा डालती हैं। भले ही पाठक व्याकरण का विशेषज्ञ न हो, पाठ में लापरवाही उसे विचलित कर सकती है।

ऊपर दिए गए सुझावों पर विचार करें, और लेख अधिक स्पष्ट हो जाएंगे - इसकी गारंटी है। इसे और भी बेहतर बनाने के लिए, हमारा उपयोग करें तकनीकी दस्तावेज़ीकरण पर काम करते समय 50 प्रश्न.

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

यह बुरा है जब दस्तावेज़ीकरण विकास के अनुरूप नहीं होता है, वास्तविक प्रश्नों का उत्तर नहीं देता है, और इसमें त्रुटियों को वर्षों तक ठीक नहीं किया जाता है। ये समस्याएँ लेखक की नहीं, बल्कि कंपनी के भीतर प्रक्रियाओं के संगठन की हैं।

दस्तावेज़ीकरण विकास के अनुरूप नहीं है

यह सुविधा पहले से ही रिलीज़ हो चुकी है, मार्केटिंग इसे कवर करने की योजना बना रही है, और फिर यह पता चलता है कि नया लेख या अनुवाद अभी भी दस्तावेज़ में नहीं है। यहां तक ​​कि हमें इसकी वजह से रिलीज भी टालनी पड़ी।' आप जितना चाहें सभी को तकनीकी लेखकों को समय पर कार्य सौंपने के लिए कह सकते हैं, लेकिन यह काम नहीं करेगा। यदि प्रक्रिया स्वचालित नहीं है, तो स्थिति अपने आप दोहराई जाएगी।

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

दस्तावेज़ीकरण उपयोगकर्ता के अनुरोधों को प्रतिबिंबित नहीं करता है

हम इस तरह काम करने के आदी हैं: एक फीचर सामने आया, हमने इसके बारे में बात की। हमने बताया कि इसे कैसे चालू करें, बंद करें और अच्छे समायोजन कैसे करें। लेकिन क्या होगा यदि कोई ग्राहक हमारे सॉफ़्टवेयर का उपयोग उस तरीके से करता है जिसकी हमें उम्मीद नहीं थी? या क्या इसमें ऐसी त्रुटियाँ हैं जिनके बारे में हमने नहीं सोचा?

यह सुनिश्चित करने के लिए कि दस्तावेज़ यथासंभव पूर्ण है, हम समर्थन अनुरोधों, विषयगत मंचों पर प्रश्नों और खोज इंजनों में प्रश्नों का विश्लेषण करने की सलाह देते हैं। सबसे लोकप्रिय विषयों को तकनीकी लेखकों को हस्तांतरित किया जाएगा ताकि वे मौजूदा लेखों को पूरक कर सकें या नए लिख सकें।

दस्तावेज़ीकरण में सुधार नहीं किया जा रहा है

इसे तुरंत पूरी तरह से करना कठिन है; फिर भी गलतियाँ होंगी। आप ग्राहकों से प्रतिक्रिया की उम्मीद कर सकते हैं, लेकिन यह संभावना नहीं है कि वे हर टाइपो, अशुद्धि, समझ से बाहर या निराधार लेख की रिपोर्ट करेंगे। ग्राहकों के अलावा, कर्मचारी दस्तावेज़ पढ़ते हैं, जिसका अर्थ है कि उन्हें वही त्रुटियाँ दिखाई देती हैं। इसका उपयोग किया जा सकता है! आपको बस ऐसी स्थितियाँ बनाने की ज़रूरत है जिसमें किसी समस्या की रिपोर्ट करना आसान हो।

हमारे पास आंतरिक पोर्टल पर एक समूह है जहां कर्मचारी दस्तावेज़ीकरण पर टिप्पणियाँ, सुझाव और विचार छोड़ते हैं। क्या समर्थन के लिए एक लेख की आवश्यकता है, लेकिन वह मौजूद नहीं है? क्या परीक्षक ने अशुद्धि देखी? क्या साझेदार ने विकास प्रबंधकों से त्रुटियों के बारे में शिकायत की है? इस समूह में सभी! तकनीकी लेखक कुछ चीज़ों को तुरंत ठीक कर देते हैं, कुछ चीज़ों को YouTrack पर स्थानांतरित कर देते हैं, और दूसरों को सोचने के लिए कुछ समय देते हैं। विषय को ख़त्म होने से बचाने के लिए, समय-समय पर हम आपको समूह के अस्तित्व और फीडबैक के महत्व की याद दिलाते हैं।

समस्या 3. सही लेख ढूंढने में काफी समय लगता है।

जो लेख नहीं मिल सकता वह उस लेख से बेहतर नहीं है जो नहीं मिल सकता। अच्छे दस्तावेज़ीकरण का आदर्श वाक्य "खोजने में आसान, ढूंढने में आसान" होना चाहिए। इसे कैसे हासिल करें?

संरचना को व्यवस्थित करें और विषयों को चुनने के सिद्धांत का निर्धारण करें. संरचना यथासंभव पारदर्शी होनी चाहिए ताकि पाठक यह न सोचें, "मुझे यह लेख कहां मिल सकता है?" संक्षेप में, दो दृष्टिकोण हैं: इंटरफ़ेस से और कार्यों से।

1. इंटरफ़ेस से. सामग्री पैनल अनुभागों की नकल करती है। पुराने ISPsystem दस्तावेज़ में यही मामला था।
2. कार्यों से. लेखों और अनुभागों के शीर्षक उपयोगकर्ताओं के कार्यों को दर्शाते हैं; शीर्षकों में लगभग हमेशा क्रियाएँ और "कैसे करें" प्रश्न के उत्तर होते हैं। अब हम इस प्रारूप की ओर बढ़ रहे हैं।'

आप जो भी दृष्टिकोण चुनें, सुनिश्चित करें कि विषय उस चीज़ के लिए प्रासंगिक है जो उपयोगकर्ता खोज रहे हैं और इस तरह से कवर किया गया है कि विशेष रूप से उपयोगकर्ता के प्रश्न का समाधान हो।

एक केंद्रीकृत खोज स्थापित करें. एक आदर्श दुनिया में, खोज तब भी काम करनी चाहिए जब आप गलत वर्तनी लिखते हैं या भाषा में कोई गलती करते हैं। कॉन्फ्लुएंस में अब तक की हमारी खोज हमें इससे प्रसन्न नहीं कर सकती। यदि आपके पास कई उत्पाद हैं और दस्तावेज़ीकरण सामान्य है, तो खोज को उस पृष्ठ के अनुरूप बनाएं जिस पर उपयोगकर्ता है। हमारे मामले में, मुख्य पृष्ठ पर खोज सभी उत्पादों के लिए काम करती है, और यदि आप पहले से ही किसी विशिष्ट अनुभाग में हैं, तो केवल उसमें मौजूद लेखों के लिए।

सामग्री और ब्रेडक्रंब जोड़ें. यह अच्छा है जब प्रत्येक पृष्ठ में एक मेनू और ब्रेडक्रंब हो - किसी भी स्तर पर लौटने की क्षमता के साथ वर्तमान पृष्ठ पर उपयोगकर्ता का पथ। पुराने ISPsystem दस्तावेज़ में, आपको सामग्री तक पहुंचने के लिए लेख से बाहर निकलना पड़ता था। यह असुविधाजनक था, इसलिए हमने इसे नए में ठीक किया।

उत्पाद में लिंक रखें. यदि लोग एक ही प्रश्न के साथ बार-बार समर्थन में आते हैं, तो इंटरफ़ेस में इसके समाधान के साथ एक संकेत जोड़ना समझ में आता है। यदि आपके पास डेटा या जानकारी है कि उपयोगकर्ता को किसी समस्या का सामना करना पड़ रहा है, तो आप उन्हें मेलिंग सूची के माध्यम से भी सूचित कर सकते हैं। उन्हें चिंता दिखाएं और समर्थन का बोझ उतारें।

पॉप-अप विंडो में दाईं ओर ISPmanager के डोमेन प्रबंधन अनुभाग में DNSSEC की स्थापना के बारे में एक लेख का लिंक है

दस्तावेज़ीकरण के भीतर क्रॉस-रेफरेंस सेट करें. जो लेख एक दूसरे से संबंधित हैं उन्हें "जुड़ा हुआ" होना चाहिए। यदि लेख अनुक्रमिक हैं, तो प्रत्येक पाठ के अंत में आगे और पीछे के तीर जोड़ना सुनिश्चित करें।

सबसे अधिक संभावना है, कोई व्यक्ति अपने प्रश्न का उत्तर ढूंढने के लिए सबसे पहले आपके पास नहीं, बल्कि किसी खोज इंजन के पास जाएगा। यदि तकनीकी कारणों से वहां दस्तावेज़ीकरण का कोई लिंक नहीं है तो यह शर्म की बात है। इसलिए सर्च इंजन ऑप्टिमाइजेशन का ध्यान रखें।

समस्या 4. पुराना लेआउट धारणा में हस्तक्षेप करता है

ख़राब पाठों के अलावा, दस्तावेज़ीकरण डिज़ाइन के कारण भी ख़राब हो सकता है। लोग अच्छी तरह से लिखी गई सामग्री पढ़ने के आदी हैं। ब्लॉग, सोशल नेटवर्क, मीडिया - सभी सामग्री न केवल सुंदर प्रस्तुत की गई है, बल्कि पढ़ने में आसान और आंखों को प्रसन्न करने वाली भी है। इसलिए, आप नीचे दिए गए स्क्रीनशॉट की तरह टेक्स्ट देखने वाले व्यक्ति का दर्द आसानी से समझ सकते हैं।

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

आपको ढेर सारे प्रभावों के साथ दस्तावेज़ का लंबा पाठ नहीं बनाना चाहिए, लेकिन आपको बुनियादी नियमों को ध्यान में रखना होगा।

लेआउट. मुख्य पाठ की चौड़ाई, फ़ॉन्ट, आकार, शीर्षक और पैडिंग निर्धारित करें। एक डिजाइनर को नियुक्त करें, और काम स्वीकार करने या इसे स्वयं करने के लिए, आर्टेम गोर्बुनोव की पुस्तक "टाइपोग्राफी एंड लेआउट" पढ़ें। यह लेआउट का केवल एक दृश्य प्रस्तुत करता है, लेकिन यह काफी पर्याप्त है।

आवंटन. निर्धारित करें कि पाठ में किस चीज़ पर जोर देने की आवश्यकता है। आमतौर पर यह इंटरफ़ेस, बटन, कोड इंसर्ट, कॉन्फ़िगरेशन फ़ाइलें, "कृपया ध्यान दें" ब्लॉक में एक पथ है। निर्धारित करें कि इन तत्वों का आवंटन क्या होगा और उन्हें नियमों में दर्ज करें। ध्यान रखें कि डिस्चार्ज जितना कम हो, उतना अच्छा है। जब उनमें से बहुत सारे होते हैं, तो पाठ शोरगुल वाला होता है। यहां तक ​​कि उद्धरण चिह्न भी शोर पैदा करते हैं यदि उनका प्रयोग बहुत बार किया जाए।

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

पाठ की लंबाई. बहुत लंबे लेखों से बचें. उन्हें भागों में तोड़ें, और यदि यह संभव नहीं है, तो लेख की शुरुआत में एंकर लिंक के साथ सामग्री जोड़ें। किसी लेख को दृश्य रूप से छोटा बनाने का एक आसान तरीका यह है कि पाठकों के एक संकीर्ण समूह के लिए आवश्यक तकनीकी विवरण को स्पॉइलर के नीचे छिपा दिया जाए।

प्रारूपों. अपने लेखों में कई प्रारूपों को संयोजित करें: पाठ, वीडियो और चित्र। इससे धारणा बेहतर होगी.

सुंदर लेआउट के साथ समस्याओं को छिपाने का प्रयास न करें। ईमानदारी से कहें तो, हमें खुद उम्मीद थी कि "रैपर" पुराने दस्तावेज़ों को सहेज लेगा - यह काम नहीं आया। ग्रंथों में इतना अधिक दृश्य शोर और अनावश्यक विवरण थे कि नियम और नए डिज़ाइन शक्तिहीन थे।

उपरोक्त में से अधिकांश आपके द्वारा दस्तावेज़ीकरण के लिए उपयोग किए जाने वाले प्लेटफ़ॉर्म द्वारा निर्धारित किया जाएगा। उदाहरण के लिए, हमारे पास संगम है। मुझे भी उसके साथ छेड़छाड़ करनी पड़ी. यदि रुचि हो, तो हमारे वेब डेवलपर की कहानी पढ़ें: सार्वजनिक ज्ञान आधार के लिए संगम: डिज़ाइन बदलना और भाषाओं द्वारा पृथक्करण स्थापित करना.

सुधार कहाँ से शुरू करें और कैसे जीवित रहें

यदि आपका दस्तावेज़ ISPsystem जितना विशाल है और आप नहीं जानते कि कहां से शुरू करें, तो सबसे बड़ी समस्याओं से शुरुआत करें। ग्राहक दस्तावेज़ को नहीं समझते हैं - पाठ में सुधार करें, नियम बनाएं, लेखकों को प्रशिक्षित करें। दस्तावेज़ीकरण पुराना हो गया है - आंतरिक प्रक्रियाओं का ध्यान रखें। सबसे लोकप्रिय उत्पादों के बारे में सबसे लोकप्रिय लेखों से शुरुआत करें: समर्थन मांगें, साइट विश्लेषण और खोज इंजन में क्वेरीज़ देखें।

आइए तुरंत कहें - यह आसान नहीं होगा। और इसके जल्दी काम करने की भी संभावना नहीं है। जब तक आप अभी शुरुआत नहीं कर रहे हैं और तुरंत सही काम नहीं कर रहे हैं। एक बात हम निश्चित रूप से जानते हैं कि यह समय के साथ बेहतर हो जाएगी। लेकिन यह प्रक्रिया कभी ख़त्म नहीं होगी :-).

स्रोत: www.habr.com