उपयोगकर्ता प्रलेखन: यह क्या बुरा है और इसे कैसे ठीक करें

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

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

समस्या 1. असंगत, खराब लिखे गए लेख

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

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

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

समस्या 2. लेख सभी सवालों के जवाब नहीं देते हैं

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

प्रलेखन विकास के साथ नहीं रहता है

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

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

प्रलेखन उपयोगकर्ता के अनुरोधों को प्रतिबिंबित नहीं करता है

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

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

प्रलेखन में सुधार नहीं किया जा रहा है

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

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

समस्या 3. आपको लंबे समय तक सही लेख देखना होगा

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

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

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

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

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

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

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


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

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

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

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

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


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

यह दस्तावेज़ीकरण से प्रभावों के एक समूह के साथ एक लंबे समय तक चलने के लायक नहीं है, लेकिन आपको बुनियादी नियमों पर विचार करने की आवश्यकता है।

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

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

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

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

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

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

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

कहाँ से सुधार करना शुरू करें और कैसे बचे

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

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