तकनीकी उत्पादों के दस्तावेज़ीकरण का उपयोग करना इतना कठिन क्यों है? (उपयोगकर्ता के दृष्टिकोण में)

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

• योगदान करने के लिए दस्तावेज़ीकरण बहुत कठिन है
  • दस्तावेज़ीकरण आसानी से पुराना हो जाता है। लोग किसी दस्तावेज़ में योगदान करने के बजाय ब्लॉग पोस्ट लिखते हैं क्योंकि इसके लिए संबंधित प्रोत्साहनों के बिना बहुत अधिक अतिरिक्त प्रयास की आवश्यकता होती है।
• संदर्भ क्लस्टर किया गया है

  • प्रलेखन स्वयं शायद ही अन्य संसाधनों से जुड़ता है। अच्छा दस्तावेज़ीकरण करने वाले संदर्भ को क्लस्टर किया जाता है।

    
    

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

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

https://nextjs.org/docs/getting-started

नेक्स्टज के प्रलेखन में एक संरचना है जो विभिन्न उत्पादों के माध्यम से लोकप्रिय है, मुझे इस संरचना को "पृथक लिस्टिंग संरचना" कहने दें। मैं उन्हें अलग-थलग कहने का कारण यह है कि वे मुख्य रूप से Next.js के पीछे के लोगों द्वारा बनाए जाते हैं (हालाँकि वे खुले स्रोत वाले हैं)।

इसके अलावा, मैं इस दस्तावेज़ीकरण के पीछे की मानसिकता को "मालिक के बुलेट-पॉइंट" के रूप में समाप्त करना चाहूंगा।

मालिक की गोली-प्वाइंट

कारण मैं इसे "मालिक का बुलेट पॉइंट" कहता हूं, दस्तावेज़ीकरण उत्पन्न करने की प्रक्रिया आमतौर पर उत्पाद स्वामी द्वारा पूरी की जाती है। किसी उत्पाद की शुरुआत में, मालिक से बेहतर समझ किसी के पास नहीं होती है। मालिक अपने उपभोक्ताओं और अनुरक्षकों के लिए उचित दस्तावेज बनाए रखने के लिए सबसे अच्छे व्यक्ति हैं।

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

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

पृथक लिस्टिंग संरचना

ई-कॉमर्स में, सामान्य प्रयोजन वाली वेबसाइटों में, आपके फ़ोन पर, और दस्तावेज़ीकरण में पृथक लिस्टिंग संरचना बहुत आम है। यह सर्वत्र है।

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

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

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

एक गतिशील संरचना की कल्पना करें, जैसे बल-निर्देशित ग्राफ (ओब्सीडियन जैसा कुछ पूरा कर सकता है या एक पेड़ आरेख, आपको उनके प्रकाशित अनुभाग [^ 1] में कई उदाहरण मिल सकते हैं)। मैं यह नहीं कह रहा हूं कि बल-निर्देशित रेखांकन या ट्री आरेख पृथक सूचीकरण संरचनाओं से बेहतर हैं। मैं चाहता हूं कि सभी को "सूचीबद्ध तरीके" से नहीं बल्कि अधिक "गतिशील तरीके से" सोचने के लिए प्रोत्साहित किया जाए, ताकि लोग अपनी आवश्यकताओं के अनुसार सबसे अच्छा विकल्प चुन सकें। वे संरचना का पता लगाने के लिए ट्री डायग्राम का उपयोग कर सकते हैं और विषयों के बीच संबंध को स्वीकार करने के लिए बल-निर्देशित ग्राफ़ का उपयोग कर सकते हैं। या हम जमीन से एक नई संरचना के साथ आ सकते हैं जो इनमें से कुछ समस्याओं को हल कर सकता है।

संयोजन में, मानसिकता और संरचना समस्या की ओर ले जाती है जो मुझे लगता है कि समस्याग्रस्त है, नीचे सूचीबद्ध है।

योगदान करने के लिए दस्तावेज़ीकरण बहुत कठिन है

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

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

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

आप तर्क दे सकते हैं कि वे एक मुद्दा पोस्ट कर सकते हैं और अपने सुझाव की व्याख्या कर सकते हैं लेकिन समस्या बनी हुई है। योगदान देने की भावना बहुत एक साथ है, यह कुछ खरीदने की भावना की तरह है। एक समानांतर दुनिया की कल्पना करें, यहां, यदि आप कुछ खरीदना चाहते हैं, तो आपको यह बताने के लिए 200 शब्द लिखने होंगे कि आप यह सामान क्यों खरीदना चाहते हैं और समुदाय को क्या लाभ है।

लोगों को नौकरशाही के साथ दस्तावेज़ीकरण में योगदान करने से रोकने की कोई आवश्यकता नहीं है। हमें एक और संरचना के साथ आने की जरूरत है जो दस्तावेज़ीकरण का अधिकार बना रहे और एक ही समय में एक साथ योगदान का लाभ उठा सके।

संदर्भ क्लस्टर किया गया है

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

कुछ समय पहले तक हम इन संदर्भों को वितरित रूप से संग्रहीत करते थे। एक नियमित ओपन-सोर्स प्रोजेक्ट उनकी चर्चा को गिटहब चर्चा या एक प्रवचन मंच, उत्पाद वेबसाइटों में उनके उपयोग के मामलों, गिटहब मुद्दों में मुद्दों, और कहीं और एक स्वयं-होस्टिंग दस्तावेज़ वेबसाइट में संग्रहीत करता है। इसके अलावा, YouTube और व्यक्तिगत ब्लॉग पोस्ट पर बहुत सारी समुदाय-जनित सामग्री है।

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

संकुल संदर्भ अस्थिर है

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

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

किसी भी संदर्भ में हर उपयोगी समाधान को हमारे पास अभी मौजूद सूचनाओं की बाढ़ के लिए प्रतिरोधी होना चाहिए। उन्हें इस युद्ध के मैदान में सर्च इंजन के अलावा बिना किसी एंकर पॉइंट के शामिल होना है।

भयानक सूची [^2] एक अच्छा विचार है, वे अच्छी सामग्री को रहने देने का एक तरीका प्रदान करते हैं, लेकिन उनके पास "पृथक लिस्टिंग संरचना" और "मालिक की बुलेट-पॉइंट" मानसिकता के साथ एक ही समस्या है।

अगर स्थिति जस की तस बनी रही...

इन मुद्दों का तत्काल परिणाम होगा "दस्तावेज़ीकरण" समय के साथ क्षय हो जाएगा। आप अमेज़ॅन वेब सेवाओं के दस्तावेज़ीकरण या Google क्लाउड दस्तावेज़ सहित कुछ तकनीकी दिग्गजों के दस्तावेज़ों पर एक नज़र डाल सकते हैं, वे सभी भारी और पढ़ने में कठिन हैं।

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

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

• उपयोगकर्ताओं को दस्तावेज़ीकरण में योगदान करने के लिए कैसे प्रोत्साहित करें और दस्तावेज़ के सामान्य उद्देश्य में हस्तक्षेप न करें? क्या हमारे पास दस्तावेज़ीकरण के लिए अधिक इंटरैक्टिव अनुभव हो सकता है? क्या कोई उपयोगकर्ता पृष्ठ को छोड़े बिना सीधे दस्तावेज़ीकरण में योगदान कर सकता है?

• एक बेहतर खोज अनुभव के लिए एक साथ संदर्भ कैसे एकत्र करें जो बाहरी खोज समाधानों पर निर्भर न हो और रास्ते में हर संदर्भ की अंतर-कनेक्टिविटी लाता हो?

• एक नई संरचना के साथ प्रयोग कैसे करें जो उपयोगकर्ता अनुभव को लाभान्वित कर सके और समय के साथ इसे पुनरावृत्त कर सके, या यहां तक कि उपयोगकर्ताओं को इसे स्वतंत्र रूप से चुनने दे?

  
  

https://twitter.com/EiffelFly

[^1]: ओब्सीडियन पब्लिश पेज [^2]: sindresorhus/awesome