डेवलपर्स के लिए तकनीकी लेखन

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

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

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

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

तकनीकी लेखन हर जगह है

पिछले साल, लोकप्रिय मैक गिट क्लाइंट, टॉवर के पीछे की टीम, 4,000 से अधिक डेवलपर्स ने मतदान किया और पाया कि उनमें से लगभग 50% लोग दिन में 3-6 घंटे कोड लिखने में बिताते हैं।

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

इसमें शामिल हो सकते हैं:

• एक नई सुविधा का प्रदर्शन,
• उस नई सुविधा का दस्तावेजीकरण,
• उस नई सुविधा से संबंधित कार्य टिकट को अपडेट करना, या
• उस नई सुविधा का समर्थन करने के लिए बैकलॉगिंग कार्य।

बेशक, बाथरूम ब्रेक और वर्डल के लिए भी हमेशा समय होता है।

वैसे भी, ज्यादातर चीजें जो हम आम तौर पर करते हैं उनमें आपकी टीम, सहकर्मियों, ग्राहकों, उपयोगकर्ताओं और अन्य डेवलपर्स जैसे लोगों के साथ संवाद करना शामिल होता है।

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

वह तकनीकी लेखन 101 है।

और बात यहीं खत्म नहीं होती.. कुछ प्रोग्रामर अपने उत्पाद खुद बनाना भी पसंद करते हैं, जिसका मतलब है कि उन्हें मार्केटिंग को अपने काम का हिस्सा बनाने की जरूरत है। तकनीकी लेखन उसमें भी बहुत बड़ी भूमिका निभाता है। तो हाँ। मुझे लगता है कि यह कहना काफी उचित है कि तकनीकी लेखन है वास्तव में हर जगह।

अच्छा व्याकरण क्या है?

इतनी सारी प्रोग्रामिंग भाषाओं के साथ, आखिरी चीज जो हम चाहते हैं वह है एक और सीखना।

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

मैं आपको भाषा के बारे में एक संक्षिप्त जानकारी देता हूं।

अंग्रेजी वाक्यविन्यास

प्रोग्रामिंग भाषाओं की तरह, अंग्रेजी में एक अच्छी तरह से परिभाषित वाक्यविन्यास है, और यह शब्दों से शुरू होता है।

शब्द अंग्रेजी के निर्माण खंड हैं, और वे आठ बाल्टी में आते हैं:

ऐसे सोचें UI घटक: वे मॉड्यूलर टुकड़े हैं जिन्हें आप एक पूर्ण और मजबूत वाक्य बनाने के लिए चारों ओर ले जा सकते हैं, वैसे ही आप एक पूर्ण और मजबूत वाक्य को एक साथ जोड़ सकते हैं UI. क्या सभी घटकों को हर समय वहाँ रहने की ज़रूरत है? हरगिज नहीं! अनुभव को पूरा करने के लिए आपको आवश्यक टुकड़ों के साथ एक वाक्य इकट्ठा करें, जैसे आप एक इंटरफ़ेस के साथ करेंगे।

आवाज और स्वर

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

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

1. मुझे प्रोग्रामिंग पसंद है।
2. I पसंद प्रोग्रामिंग! :)

स्वर के लिए आवाज को भ्रमित करना आसान है, और इसके विपरीत।

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

एक ही संदेश, दो अलग-अलग स्वरों में लिखा गया:

• मज़ा: "अपने सोशल नेटवर्क का विस्तार करें और अभी जो ट्रेंड कर रहा है उस पर अपडेट रहें।"
• गंभीर: "सबसे बड़े सोशल नेटवर्किंग ऐप और ऑनलाइन जॉब मार्केट में से एक पर जॉब खोजें।"

गलती से ऐसे संदेश लिखना असामान्य नहीं है जो कृपालु, आपत्तिजनक और गैर-पेशेवर के रूप में सामने आते हैं। यह कहाँ है स्वर खेलने के लिए आता है। अपने संदेशों को ज़ोर से पढ़ें, अन्य लोगों को अपने लिए उन्हें पढ़ने के लिए कहें, और अपने विराम चिह्न और वाक्य संरचना के साथ प्रयोग करें। इस तरह आप अपने स्वर में सुधार करते हैं।

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

सक्रिय और निष्क्रिय आवाज

एक वाक्य में हमेशा एक अभिनेता, एक क्रिया और एक लक्ष्य होता है। जिस क्रम में ये आते हैं यह निर्धारित करता है कि वाक्य सक्रिय या निष्क्रिय आवाज में लिखा गया है या नहीं।

अभिनेता सबसे पहले आता है सक्रिय आवाज. उदाहरण के लिए: "सीएसएस पृष्ठभूमि को पेंट करता है।"

सक्रिय स्वर का उपयोग करने वाले वाक्य अपने समकक्षों की तुलना में अधिक सीधे होते हैं। वे स्पष्ट, छोटे और अधिक समझने योग्य हैं - एक अधिक पेशेवर आवाज के लिए एकदम सही जो सीधे बिंदु पर पहुंचती है।

एक साथ कर्मवाच्य, अभिनेता अंतिम आता है। (देखें कि मैंने वहां क्या किया?) इसका मतलब है कि हमारे अभिनेता - इस मामले में सीएसएस - इस तरह से अंत में आता है: "पृष्ठभूमि को सीएसएस द्वारा चित्रित किया गया है।"

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

लेकिन इसका मतलब यह नहीं है कि आपको हमेशा सक्रिय आवाज के लिए प्रयास करना चाहिए। एक से दूसरे में स्विच करना - यहां तक ​​कि एक ही पैराग्राफ में - प्रभावी ढंग से उपयोग किए जाने पर आपकी सामग्री को एक वाक्य से दूसरे वाक्य में प्रवाहित किया जा सकता है।

गलतियों से बचना

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

इस लेख के अंत में, मैं आपको अमूल्य उपकरण दिखाऊंगा जो पेशेवर लेखन की गलतियों से बचने के लिए उपयोग करते हैं। जाहिर है, इन दिनों लगभग हर चीज में अंतर्निहित वर्तनी जांचकर्ता हैं; हमारे कोड संपादकों के पास गलतियों को रोकने में मदद करने के लिए वर्तनी-जांच और लाइनिंग प्लगइन्स भी हैं। 

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

कोड टिप्पणियाँ लिखना

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

यह दिलचस्प है कि प्रत्येक प्रोग्रामिंग भाषा टिप्पणी लिखने के लिए सुविधाओं के एक मानक सेट के साथ आती है। उन्हें समझाना चाहिए कि कोड क्या कर रहा है। उसके द्वारा, मेरा मतलब इस तरह की अस्पष्ट टिप्पणियों से नहीं है:

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

इसके बजाय, अधिक जानकारी प्रदान करने वाली टिप्पणियों का उपयोग करें:

red *= 1.2 // Apply a 'reddish' effect to the image

यह सब संदर्भ के बारे में है। "मैं किस तरह का कार्यक्रम बना रहा हूं?" ठीक उसी तरह का सवाल है जो आपको खुद से पूछना चाहिए।

टिप्पणियों को मूल्य जोड़ना चाहिए

इससे पहले कि हम देखें कि "अच्छा" कोड क्या टिप्पणी करता है, यहाँ आलसी टिप्पणियों के दो उदाहरण हैं:

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

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

टिप्पणियों को वर्तमान कोड को प्रतिबिंबित करना चाहिए

बड़ी परियोजनाओं में पुरानी टिप्पणियां दुर्लभ नहीं हैं; हिम्मत मैं कहता हूँ अधिकांश परियोजनाओं.

आइए कल्पना करें कि डेविड, एक प्रोग्रामर और एक शांत आदमी है जिसके साथ घूमने जाना है। डेविड ए से जेड तक वर्णानुक्रम में तारों की एक सूची को सॉर्ट करना चाहता है, इसलिए वह जावास्क्रिप्ट में स्पष्ट करता है:

cities = sortWords(cities) // sort cities from A to Z

डेविड को तब पता चलता है कि सॉर्टवर्ड्स () वास्तव में जेड से ए तक सूचियों को सॉर्ट करता है। यह कोई समस्या नहीं है, क्योंकि वह केवल आउटपुट को उलट सकता है:

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

दुर्भाग्य से, डेविड ने अपनी कोड टिप्पणी अपडेट नहीं की।

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

हालांकि यह एक अतिरंजित उदाहरण हो सकता है, यदि आप एक करीबी समय सीमा के खिलाफ दौड़ रहे हैं तो कुछ ऐसा ही हो सकता है (और अक्सर होता है)। शुक्र है, एक साधारण नियम का पालन करके इसे रोका जा सकता है… अपनी टिप्पणियों को उसी समय बदलें जब आप कोड बदलते हैं।

यह एक आसान सा नियम है जो आपको और आपकी टीम को बहुत सी चीजों से बचाएगा तकनीकी ऋण.

अब जब हम जानते हैं कि खराब लिखी गई टिप्पणियाँ कैसी दिखती हैं, आइए कुछ अच्छे उदाहरण देखें।

टिप्पणियों में एक मुहावरेदार कोड की व्याख्या करनी चाहिए

कभी - कभी प्राकृतिक काम करने का तरीका सही नहीं है। प्रोग्रामर को मानकों को थोड़ा "तोड़ना" पड़ सकता है, लेकिन जब वे ऐसा करते हैं, तो उनके औचित्य को समझाते हुए एक छोटी सी टिप्पणी छोड़ने की सलाह दी जाती है:

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

यह मददगार है, है ना? यदि आप इस कोड की समीक्षा करने के लिए ज़िम्मेदार थे, तो हो सकता है कि आप उस टिप्पणी के बिना इसे सही करने के लिए परीक्षा दे रहे हों कि क्या हो रहा है।

टिप्पणियाँ भविष्य के कार्यों की पहचान कर सकती हैं

टिप्पणियों के साथ करने के लिए एक और उपयोगी बात यह स्वीकार करना है कि अभी और काम किया जाना है।

// TODO: use a more efficient algorithm
linearSort(ids)

इस तरह, आप अपने प्रवाह पर ध्यान केंद्रित कर सकते हैं। और बाद की तारीख में, आप (या कोई और) वापस आकर इसे ठीक कर सकते हैं।

टिप्पणियाँ स्रोत से वापस लिंक कर सकती हैं

तो, आपने अभी StackOverflow पर अपनी समस्या का समाधान ढूंढा है। उस कोड को कॉपी-पेस्ट करने के बाद, कभी-कभी उस उत्तर का लिंक रखना एक अच्छी बात है जिससे आपको मदद मिली ताकि आप भविष्य के संदर्भ के लिए उस पर वापस आ सकें।

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

यह महत्वपूर्ण है क्योंकि समाधान बदल सकते हैं। यह जानना हमेशा अच्छा होता है कि आपका कोड टूटने की स्थिति में कहां से आया है।

पुल अनुरोध लिखना

अनुरोधों को खींचो (PRs) किसी भी परियोजना का एक मूलभूत पहलू हैं। वे कोड समीक्षाओं के केंद्र में हैं। और बिना अच्छे शब्दों के आपकी टीम के प्रदर्शन में कोड समीक्षाएं जल्दी से एक अड़चन बन सकती हैं।

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

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

अस्पष्ट से बचें PR खिताब

कृपया इस तरह दिखने वाले शीर्षकों से बचें:

• बिल्ड को ठीक करें।
• बग को ठीक करो।
• पैच जोड़ें।

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

PR शीर्षक पारंपरिक रूप से में लिखे जाते हैं अनिवार्य काल. वे संपूर्ण का एक-पंक्ति सारांश हैं PR, और उन्हें वर्णन करना चाहिए क्या द्वारा किया जा रहा है PR.

यहां कुछ अच्छे उदाहरण दिए गए हैं:

• NgOptimizedImage में कस्टम srcset विशेषताओं का समर्थन करें
• 75% छवि गुणवत्ता के लिए डिफ़ॉल्ट छवि विन्यास
• सभी अंतर्निहित ControlValueAccessors के लिए स्पष्ट चयनकर्ता जोड़ें

लंबे समय से बचें PRs

एक बड़े PR इसका मतलब एक विशाल विवरण है, और कोई भी कोड की सैकड़ों या हजारों पंक्तियों की समीक्षा नहीं करना चाहता है, कभी-कभी केवल पूरी बात को खारिज करने के लिए!

इसके बजाय, आप कर सकते थे:

• के माध्यम से अपनी टीम के साथ संवाद करें मुद्दे,
• एक योजना बना,
• समस्या को छोटे टुकड़ों में बांटें, या
• प्रत्येक टुकड़े पर अपने स्वयं के साथ अलग से काम करें PR.

क्या यह अब ज्यादा साफ नहीं है?

में विवरण प्रदान करें PR परिवर्तन

भिन्न PR शीर्षक, शरीर है la सभी विवरणों के लिए जगह, जिसमें शामिल हैं:

• क्यों है PR किया जा?
• यह सबसे अच्छा तरीका क्यों है?
• दृष्टिकोण में कोई कमी, और यदि संभव हो तो उन्हें हल करने के लिए विचार
• बग या टिकट नंबर, बेंचमार्क परिणाम, आदि।

बग की सूचना देना

बग रिपोर्ट किसी भी परियोजना के सबसे महत्वपूर्ण पहलुओं में से एक है। और सभी बेहतरीन प्रोजेक्ट यूजर फीडबैक पर बनाए गए हैं। आमतौर पर, अनगिनत परीक्षणों के बाद भी, यह उपयोगकर्ता ही होते हैं जो अधिकांश बग ढूंढते हैं। उपयोगकर्ता भी महान आदर्शवादी होते हैं, और कभी-कभी उनके पास फीचर विचार होते हैं; कृपया उन्हें सुनें!

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

उदाहरण के लिए, अधिकांश बड़ी परियोजनाएं साथ आती हैं टेम्पलेट:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

स्क्रीनशॉट इकट्ठा करें

अपने . का उपयोग करके समस्या को कैप्चर करें सिस्टम की स्क्रीन-शूटिंग उपयोगिता.

अगर यह a . का स्क्रीनशॉट है सीएलआई कार्यक्रम, सुनिश्चित करें कि पाठ स्पष्ट है। अगर यह एक है UI कार्यक्रम, सुनिश्चित करें कि स्क्रीनशॉट सही तत्वों और राज्यों को कैप्चर करता है।

समस्या को प्रदर्शित करने के लिए आपको वास्तविक इंटरैक्शन कैप्चर करने की आवश्यकता हो सकती है। अगर ऐसा है, तो कोशिश करें स्क्रीन-रिकॉर्डिंग टूल का उपयोग करके GIF रिकॉर्ड करें.

समस्या को पुन: उत्पन्न कैसे करें

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

यहाँ एक उदाहरण दिया गया है:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

एक कारण सुझाएं

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

यह कोडबेस का पता लगाने के लिए भी चोट नहीं पहुंचा सकता है, और शायद यह पहचान सकता है कि समस्या क्या है। फिर, आपकी समस्या बहुत जल्दी बंद हो जाएगी और आपको संबंधित को सौंपे जाने की संभावना है PR.

ग्राहकों के साथ संचार

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

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

तो, हम उस स्टीरियोटाइप को कैसे कम करते हैं? ग्राहकों से पूछें कि वे क्या चाहते हैं, और हमेशा उनकी प्रतिक्रिया सुनें। यहाँ यह कैसे करना है।

सही प्रश्न पूछें

यह सुनिश्चित करके प्रारंभ करें कि आप और ग्राहक एक ही पृष्ठ पर हैं:

• आपके टारगेट ऑडिएन्स कौन हैं?
• साइट का लक्ष्य क्या है?
• आपका निकटतम प्रतियोगी कौन है और वे क्या सही कर रहे हैं?

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

• क्या आप इसके साथ ठीक हैं, भले ही यह अतिरिक्त प्रदर्शन लागत के साथ आता हो?
• क्या घटक को स्थानांतरित करने से हमें अपने उद्देश्य को बेहतर ढंग से पूरा करने में मदद मिलती है?
• बढ़िया, लॉन्च के बाद इसे बनाए रखने के लिए कौन जिम्मेदार है? 
• क्या आप जानते हैं कि अगर उन दो रंगों के बीच का कंट्रास्ट WCAG AA मानकों को पूरा करता है?

प्रश्न बहुत अधिक निर्दोष हैं और शत्रुता पर जिज्ञासा को बढ़ावा देते हैं।

अपने आप को बेचें

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

• जो आप हैं
• आप क्या करते हो
• आप नौकरी के लिए उपयुक्त क्यों हैं
• आपके द्वारा किए गए प्रासंगिक कार्य के लिंक

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

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

माइक्रोकॉपी लिखना

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

शायद इसीलिए हमें कभी-कभी इस तरह की त्रुटियाँ दिखाई देती हैं:

Error: Unexpected input (Code 693)

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

तकनीकी शब्दजाल से बचें

अधिकांश लोग नहीं जानते कि सर्वर क्या है, जबकि 100% प्रोग्रामर करते हैं। इसलिए त्रुटि संदेश में लिखे गए असामान्य शब्दों को देखना असामान्य नहीं है, जैसे API या "समयबाह्य निष्पादन।"

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

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

उपयोगकर्ता को कभी दोष न दें

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

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

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

उपयोगकर्ता को अभिभूत न करें

अपनी माइक्रोकॉपी में हास्य का उपयोग करना एक अच्छा विचार है! यह मूड को हल्का कर सकता है, और यह सबसे खराब त्रुटियों के कारण होने वाली नकारात्मकता को रोकने का एक आसान तरीका है।

लेकिन अगर आप इसका इस्तेमाल नहीं करते हैं पूरी तरह से, यह उपयोगकर्ता के लिए कृपालु और अपमानजनक के रूप में सामने आ सकता है। यह सिर्फ एक है बड़ा लेने का जोखिम।

Mailchimp इसे अच्छी तरह से कहता है:

[डी] मजाक बनाने के लिए अपने रास्ते से बाहर मत जाओ - मजबूर हास्य किसी से भी बदतर नहीं हो सकता है। यदि आप अनिश्चित हैं, तो सीधा चेहरा रखें.

(जोर मेरा)

सुलभ मार्कअप लिखना

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

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

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

इस तरह की चीजें:

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

निष्कर्ष

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

निचली पंक्ति: अपने लेखन कौशल को तेज करना और अपने लेखन में थोड़ा अतिरिक्त प्रयास करना वास्तव में आपको एक बेहतर डेवलपर बना सकता है।

तकनीकी लेखन संसाधन

यदि आप तकनीकी लेखन में रुचि रखते हैं:

यदि आप कॉपी राइटिंग में रुचि रखते हैं:

यदि आप माइक्रोकॉपी में रुचि रखते हैं:

यदि आप अपने लेखन को बेहतर बनाने के लिए किसी पेशेवर शैली मार्गदर्शिका का उपयोग करने में रुचि रखते हैं:

यदि आप अभिगम्यता के लिए लिखने में रुचि रखते हैं: