2016 के पतन में, मेरे सहयोगी और मुझे अपनी पूर्व कंपनी में प्रलेखन और सामग्री में सुधार करने का निर्देश दिया गया था। हमने सभी प्रकार के प्रलेखन पर एक वर्ष बिताया: एपीआई संदर्भ, गाइड, ट्यूटोरियल, ब्लॉग पोस्ट। इससे पहले, मैंने 5 साल के लिए गोदी लिखा था, लेकिन मैंने आधिकारिक तौर पर यह नहीं सीखा। लेकिन मुझे अनुभवहीन नहीं कहा जा सकता: परियोजनाओं और स्टार्टअप के लिए एपीआई का दस्तावेजीकरण करने के अलावा, मैंने विश्वविद्यालय में अंतिम पाठ्यक्रमों में अध्ययन करते समय सेमिनारों में पायथन फ्लास्क भी पढ़ाया। लेकिन अब यह केवल मेरे पसंदीदा व्यवसाय पर ध्यान केंद्रित करने का एक अवसर है: तकनीकी दस्तावेज के माध्यम से सभी स्तरों पर विशेषज्ञों की मदद करना।

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

लोग वास्तव में प्रलेखन कैसे पढ़ते हैं?

"एक राष्ट्र एक ही पाठ के एक बड़े टुकड़े पर shudders", प्याज द्वारा फोटो

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

2006 के नीलसन नॉर्मन ग्रुप लुक-अप अध्ययन में , 232 उपयोगकर्ताओं ने हजारों वेब पेज देखे। यह पता चला कि उपयोगकर्ता आमतौर पर एफ-पैटर्न का उपयोग करते हुए पृष्ठों को देखते हैं:

1. “पहले वे क्षैतिज दिशा में पढ़ते हैं, आमतौर पर सामग्री क्षेत्र के ऊपरी हिस्से में। यह F का शीर्ष तत्व है। "
2. "फिर वे पृष्ठ को थोड़ा नीचे ले जाते हैं - और एक दूसरा क्षैतिज आंदोलन करते हैं, जो आमतौर पर पिछले एक की तुलना में कम क्षेत्र को कवर करता है। यह अतिरिक्त तत्व आकृति F के मध्य तत्व को बनाता है ”।
3. “अंत में, उपयोगकर्ता सामग्री के बाईं ओर लंबवत स्कैन करते हैं। कभी-कभी यह एक धीमी और व्यवस्थित स्कैन होती है, जिसे हीटमैप पर एक ठोस पट्टी के रूप में प्रदर्शित किया जाता है। कभी-कभी आंदोलन तेज होता है, जिससे हीटमैप पर धब्बे बन जाते हैं। यह आंकड़ा एफ में अंतिम ऊर्ध्वाधर तत्व है। "

हीटमैप्स नीलसन नॉर्मन ग्रुप

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

यह ध्यान रखना महत्वपूर्ण है कि एफ-पैटर्न उपयोगकर्ताओं के रास्ते में है , लेकिन सामग्री की अच्छी स्थिति एफ-स्कैन को रोकने में मदद करती है।

प्रलेखन के लिए विशिष्ट निहितार्थ क्या हैं?

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

तो पृष्ठ पर सामग्री को कैसे संरचित करें?

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

मैंने केविन बर्क के व्याख्यान, "हाउ टू राइट डॉक्यूमेंटेशन फॉर यूज़र्स हू डोंट रीड इट" से इनमें से कुछ युक्तियों को सीखा। केविन ने 2011 से 2014 तक ट्विलियो प्रलेखन का समर्थन किया।

इसके अलावा, पैराग्राफ की अपनी विशिष्टताएं होती हैं। द प्याज के पाठ की तरह, जब आप बहुत सारे पैराग्राफ पढ़ते हैं, तो आप जिस्ट को छोड़ सकते हैं। फिर उनका इतनी बार उपयोग क्यों? आइए Keen IO प्रलेखन से एक प्रयोग करते हैं:

जल्दी से इसे पढ़ें:

इवेंट सेट में लगभग कोई भी नाम हो सकता है, लेकिन कई नियम हैं: नाम में 64 से अधिक वर्ण नहीं होने चाहिए। इसमें केवल ASCII अक्षर होने चाहिए। यह शून्य नहीं हो सकता।

अब जल्दी से इसे पढ़ें:

इवेंट सेट में लगभग कोई भी नाम हो सकता है, लेकिन कुछ नियम हैं:

• शीर्षक 64 अक्षरों से अधिक नहीं होना चाहिए
• इसमें केवल ASCII अक्षर होने चाहिए
• यह शून्य नहीं हो सकता

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

बाद में हम प्रलेखन और नेविगेशन के बारे में अधिक विस्तार से चर्चा करेंगे।

कोड उदाहरण

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

नमूना कोड में संदर्भ डेवलपर की सफलता के लिए महत्वपूर्ण है। डेवलपर्स जल्दी से कॉपी और पेस्ट करना पसंद करते हैं। यहाँ Keen IO API के साथ एक उदाहरण दिया गया है:

var client = new Keen({ projectId: "your_project_id", writeKey: "your_write_key" }); var ticketPurchase = { price: 50.00, user: { id: "020939382", age: 28 }, artist: { id: "19039", name: "Tycho" } } client.addEvent("ticket_purchases", ticketPurchase); 

डेवलपर इस कोड को जल्दी से कॉपी और पेस्ट कर देता है। और ...



सबसे पहले, वे फ़ाइल को कैसे चलाते हैं? शायद node file_name.js तरह node file_name.js , लेकिन यह कोड में नहीं है। शीर्ष पर टिप्पणियों में संकेत दे सकता है।

खैर, उन्होंने इसे शुरू कर दिया और ... ReferenceError: Keen is not defined । :-( कीन क्लाइंट शुरू नहीं किया गया था, शीर्ष पर कोई आयात या बयान की आवश्यकता नहीं है, और यह केवल एनपीएम लाइब्रेरी स्थापित करने के बाद काम करता है।

उपयोगकर्ता ने इसे ठीक किया और इसे फिर से चलाया ... लगता है! एक और गलती! your_project_id और your_write_key गायब हैं।

यह सब और अधिक स्पष्ट किया जा सकता है।

यहाँ Twilio प्रलेखन से एक उदाहरण है जो अंत उपयोगकर्ता के लिए एक अच्छा संदर्भ प्रदान करता है:


ट्विलियो नोड हेल्पर लाइब्रेरी प्रलेखन से स्क्रीनशॉट

यह तुरंत स्पष्ट करता है कि लाइब्रेरी को कैसे स्थापित किया जाए, इसे अपने कोड में एम्बेड करें और इसे चलाने से पहले नमूना कोड में क्या बदला जाना चाहिए।

कॉपी-पेस्ट कीड़े

चूंकि हमारे पास प्रलेखन में बहुत सारे नमूना कोड हैं, इसलिए सफल कॉपी-पेस्ट एक महत्वपूर्ण संपत्ति है। यहां दो उदाहरण दिए गए हैं, जहां इसका सम्मान नहीं किया जाता है:

 #      $ gem install rails 

बहुत हानिरहित लगता है, है ना? फिर से सोचें, जब आप इसे कमांड लाइन में कॉपी और पेस्ट करते हैं तो क्या होता है? आप सबसे अधिक संभावना प्राप्त करेंगे:

 bash: command not found: $ 

एक आम गलती। या तो आप चाहते हैं कि कमांड लाइन पर कमांड दिखे, या आप गलती से इसे कॉपी कर लें। मैं $ देने की सलाह दूंगा। आप इस प्रतीक के कॉपी-पेस्ट को प्रतिबंधित करने का एक तरीका भी ढूंढ सकते हैं ताकि त्रुटि उपयोगकर्ताओं को परेशान न करे।

एक और हालिया उदाहरण: क्या आपने यह जांचा कि उपयोगकर्ता को कॉपी करना चाहते कोड को उजागर करना कितना आसान है?

Kelsey Hightower ने Google क्लाउड नेक्स्ट प्रेजेंटेशन में StackOverflow से नमूना कोड को कॉपी करने के लिए संघर्ष किया।


"अच्छे प्रोग्रामर कॉपी, महान प्रोग्रामर पेस्ट"

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

"वह सब!"

"वह सब!" वाक्यांश संदर्भ से बाहर बहुत हानिरहित लगता है, लेकिन कल्पना करें कि "आसान", "सरल", "तुच्छ" और "सरल" जैसे कुछ शब्द जब समस्याएँ होती हैं - महान नहीं होती हैं! जब कोई व्यक्ति एपीआई कार्य करने की कोशिश में फंस जाता है, तो ऐसा वाक्यांश उसकी बुद्धिमत्ता पर संदेह करता है और उससे सवाल पूछता है: "तो क्या यह मूर्ख है?" यह demoralizes।

अति सरलीकरण

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

सहानुभूति

शब्दों का चुनाव वास्तव में मायने रखता है। सहानुभूति दूसरों की भावनाओं को समझने और साझा करने की क्षमता है। जब हम सहानुभूति दिखाते हैं, तो हम न केवल नवागंतुकों, बल्कि अधिक उन्नत उपयोगकर्ताओं की भी मदद करते हैं। यह उपयोगकर्ताओं की संभावित संख्या बढ़ाने, मामलों, ग्राहकों और यहां तक ​​कि कंपनी के राजस्व का उपयोग करने में मदद करता है।

लेकिन जब प्रलेखन एक विशेषज्ञ परियोजना डेवलपर द्वारा लिखा जाता है, तो सहानुभूति अधिक कठिन होती है। यहाँ कुछ उपयोगी सुझाव दिए गए हैं जिन्होंने मुझे अतीत में मदद की है:

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

एक प्रकार के प्रलेखन के रूप में त्रुटि संदेश

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

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

केट का कहना है कि अच्छे त्रुटि संदेश तीन सिद्धांतों पर बनाए गए हैं:

• शील
• मानवता
• उपयोगिता

शील

आपको तुरंत माफी माँगने की ज़रूरत है, भले ही यह आपकी गलती न हो। मैं इसका समर्थन सेवा में भी अभ्यास करता हूं।

एक उदाहरण:

क्षमा करें, ___ से कनेक्ट नहीं हो सका। कृपया अपनी नेटवर्क सेटिंग जांचें, उपलब्ध नेटवर्क से कनेक्ट करें और फिर से प्रयास करें।

मानवता

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

उदाहरण (Twilio 401 स्थिति कोड त्रुटि):

 { “code”: 20003, “detail”: “Your AccountSid or AuthToken was incorrect.”, “message”: “Authenticate”, “more_info”: “https://www.twilio.com/docs/errors/20003", “status”: 401 } 

उपयोगिता

यदि आप इन युक्तियों में से एक को याद करते हैं, तो उपयोगिता याद रखें। समस्या को ठीक करने के बारे में उपयोगकर्ता के साथ जानकारी साझा करें।

एक उदाहरण:

क्षमा करें, आपके द्वारा अपलोड की गई छवि बहुत बड़ी है। ऊँचाई में 4000px से कम और चौड़ाई में 4000px से कम छवियों के साथ फिर से प्रयास करें।

त्रुटि संदेश कैसे लिखें

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

खराब उदाहरण:

पिछले पृष्ठ पर वापस जाने के लिए बैक बटन दबाएं।

अच्छा उदाहरण:

पिछले पृष्ठ पर लौटने के लिए, बैक बटन का उपयोग करें।

प्रलेखन त्रुटि संदेश

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

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

20003 त्रुटि (स्थिति कोड 401 की त्रुटि, पहले उल्लेख किया गया) के मामले में, कई संभावित कारण हैं जो स्पष्ट रूप से कैटलॉग में बताए गए हैं।


स्रोत: https://www.twilio.com/docs/api/errors

स्ट्राइप विभिन्न त्रुटि कोडों के विस्तृत विवरण के साथ कुछ ऐसा ही करता है।




स्रोत: https://www.twilio.com/docs/api/errors

तुम भी StackOverflow सवालों में अपनी त्रुटि संदेश पा सकते हैं। उन्हें मामूली, मानवीय और लाभ के साथ जवाब दें। एसईओ के कारण, उपयोगकर्ता अक्सर वास्तविक दस्तावेज के बजाय StackOverflow पर आपके त्रुटि संदेशों के साथ समाप्त होते हैं।

संकेत: यदि किसी ने मामूली, मानवीय और लाभ के साथ जवाब नहीं दिया है, तो पर्याप्त "प्रतिष्ठा" के साथ आप स्टैकऑवरफ्लो उत्तरों को संपादित कर सकते हैं।

शब्द चयन

कई शब्दों में अच्छी तरह से स्थापित मानसिक पैटर्न होते हैं। उदाहरण के लिए, "लाइब्रेरी", एसडीके, "रैपर" और "क्लाइंट" जैसे शब्द पहले से ही अतिभारित हैं और पाठक के ध्यान से गुजरते हैं।

अपने व्याख्यान में, "यहां तक ​​कि इस व्याख्यान के लिए, राइट टू डॉक्स पर एक नाम ढूंढना मुश्किल है" , रूटी बेंडरर का कहना है कि सही शब्दों को चुनना इतना मुश्किल क्यों हो सकता है।

हम अक्सर शब्दों को खराब तरीके से चुनते हैं, हालांकि पाठ लिखते समय हम हर समय ऐसा करते हैं। कई एसडीके शीर्षकों की तरह, प्रत्येक शब्द पाठक में भावनाओं, विचारों और परिभाषाओं की एक विस्तृत श्रृंखला को विकसित करता है। आप इसे नहीं समझ सकते हैं - और अक्सर हम गलत धारणाएं बनाते हैं।

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

क्यों खराब वस्तु नाम (या प्रलेखन) संरक्षित हैं?

ओवरसाइम्प्लिफिकेशन के साथ, हम अक्सर यह नहीं समझते हैं कि नाम खराब है। इसे रूठी ने सहानुभूति की विफलता कहा है । यह कैसे कहा जाए कि असफल शब्दों की समस्या मुझे चिंतित नहीं करती है, इसलिए यह मौजूद नहीं है।

संयुक्त राज्य अमेरिका के लिए संकेत: आकस्मिक नस्लवाद को रोकने के लिए, "काले" और "सफेद" के बजाय "निषिद्ध सूची" और "अनुमत सूची" शब्दों का उपयोग करें।
(स्रोत: आंद्रे स्टाल्ट्ज़ और रेल / रेल / मुद्दे / 33677 )

यह अभी भी मुझे याद दिलाता है कि रूटी एक नौसिखिया सोच वाली गलती क्या कहती है । यह कहना पसंद है "यह मेरे लिए पूरी तरह से स्पष्ट है। मैं यह नहीं समझता कि कोई इसे कैसे समझ नहीं सकता है। ”

अंत में, रूटी ने एक स्थानीयकरण त्रुटि का उल्लेख किया। उदाहरण के लिए, चीनी भाषा में बिंग शब्द का अर्थ है "बीमार।"

2017 के GitHub ओपन सोर्स सर्वे अध्ययन के अनुसार :

लगभग 25% डेवलपर्स अंग्रेजी पढ़ते हैं और लिखते हैं "बहुत अच्छा नहीं है।" किसी परियोजना में संचार करते समय, गैर-अंग्रेजी भाषी देशों के लोगों के लिए एक समझने योग्य और सुलभ भाषा का उपयोग करें।

प्रलेखन में अमेरिकी और मुहावरों का उपयोग करते समय क्या आप इसे ध्यान में रखते हैं? उनमें से कई उपयोगकर्ताओं के लिए समझ से बाहर हो सकते हैं।

संकेत: मेरा मानना ​​है कि इन समस्याओं को हल करने के लिए सबसे बड़ी "चाल" में से एक प्रलेखन टीम की विविधता है।

अभी भी ऐसे मामले हैं जब हम एक गलती स्वीकार करते हैं, लेकिन हम इसे ठीक नहीं कर सकते हैं या नहीं करना चाहते हैं, क्योंकि हम ...

• उसे बांध दिया
• हमें समय नहीं मिलता है
• हम महत्व नहीं देखते हैं
• इसे ठीक करने के लिए हमारे पास कोई एजेंसी नहीं है।

आप कह सकते हैं या सुन सकते हैं: "लेकिन यह मेरा दिमाग है!", "मेरी स्वीटी को किसने निकाला?" "अगर हम नाम बदल देते हैं, तो सब कुछ टूट जाएगा", "मुझे विश्वास नहीं है कि इस नाम को बदलने से कुछ महत्वपूर्ण प्रभावित होगा।"

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

सही शब्दों का चयन कैसे करें?

शुरू करने के लिए, मैं एक सवाल पूछने की सलाह देता हूं: आपके उपयोगकर्ता किन शब्दों का उपयोग करते हैं? विभिन्न प्रोग्रामर सर्कल अलग-अलग शब्दों का उपयोग करते हैं, दूसरों का उपयोग करने की कोशिश न करें। यह न केवल पाठकों के लिए, बल्कि खोज और एसईओ के लिए भी उपयोगी है।

अंत में, सब कुछ अनिवार्य रूप से व्यक्तिपरक मूल्यांकन के लिए नीचे आता है। हालांकि, विचार करने के लिए कुछ सिद्धांत हैं। रूटी का कहना है कि बुरे नाम वे हैं जो कर सकते हैं:

• भ्रामक
• परेशान करने के लिए
• गुमराह
• भ्रमित करना
• उल्लंघन

दूसरी ओर अच्छे नाम:

• अचानक स्पष्टीकरण में योगदान ("यही है!")
• संदर्भ में इंजेक्शन
• समझाया
• प्रकाश
• सहायता प्रदान करें

मैं इन गुणों को खाते में लेने की सलाह देता हूं जब इसके बारे में उपयोगी और ईमानदार समीक्षा करने के लिए प्रलेखन में कटौती की जाती है।

सही शब्दों का चयन करना मुश्किल है। कोई जादू सूत्र नहीं है। सभी उपयोगकर्ता अलग-अलग हैं, जैसा कि उत्पाद उपयोग के मामले हैं; कुछ के लिए काम करने वाले दूसरों के लिए काम नहीं कर सकते हैं। अगर यह आसान होता, तो सभी के पास बहुत बेहतर दस्तावेज होते। जैसा कि रूटी डेवलपर्स को बताता है: “लेखन कार्यक्रम नामों का आविष्कार करने में एक अभ्यास है। इससे निपटो। ” और यदि आप किसी और के कार्यक्रम के लिए दस्तावेज लिख रहे हैं, तो "डेवलपर को बताएं कि क्या उसके नाम लक्ष्य से नहीं टकराए"।