कोडलैब लिखना

परिचय

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

कोडलैब लिखना, कम्यूनिटी में योगदान करने का एक बेहतरीन तरीका है. इससे आपको अपनी जानकारी शेयर करने में मदद मिलती है. साथ ही, इससे उस डेवलपर के लिए काम आसान हो जाता है जिसे यह समस्या आ रही है.

अच्छा कोडलैब किसे माना जाता है?

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

प्रोसेस

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

लेखन युक्तियां

इस पेज के बाकी हिस्से में, कोडलैब लिखने के बारे में कुछ सुझाव और सवाल दिए गए हैं.

तकनीकी लेखन के बारे में खास जानकारी पाने के लिए, तकनीकी लेखन एक देखें.

ऑडियंस

• टारगेट किए गए दर्शक कौन हैं?
• उन्हें Blockly इस्तेमाल करने के बारे में पहले से क्या-क्या पता है?
• वे क्या सीखने की कोशिश कर रहे हैं?

सेटअप

• आपके कोड को चलाने के लिए, उपयोगकर्ता को कम से कम क्या सेटअप करना होगा?

अगर आपको लगता है कि इससे मदद मिलेगी, तो examples डायरेक्ट्री में स्टार्टर कोड और पूरा कोड पब्लिश करें.

बनावट

किसी भी तरह का कॉन्टेंट लिखने से पहले, उसकी रूपरेखा तैयार करें. यह ज़्यादातर कोडलैब के लिए एक अच्छा स्ट्रक्चर है:

• शुरुआती जानकारी
  • आपको क्या सीखने को मिलेगा
  • आपको क्या बनाना है
  • आपके काम की जानकारी
  • सेटअप करने के बारे में निर्देश
• पहला चरण: [यहां टाइटल डालें]
  • वजह/जानकारी
  • कोड सैंपल
  • अनुमानित नतीजे
  • (ज़रूरी नहीं) ज़्यादा जानकारी
• ...
• दसवां चरण: [टाइटल यहां डालें]
• खास जानकारी
  • आपको क्या सीखने को मिला
  • आपने क्या बनाया
  • अन्य संसाधन
  • पूरे कोड का लिंक (अगर उपलब्ध हो)

हालांकि, आपके पास दस से ज़्यादा चरण हो सकते हैं, लेकिन अगर आपके पास बीस चरण हैं, तो आपको इसे दो कोडलैब में बांटने के बारे में सोचना चाहिए.

लिखने का तरीका

• बातचीत वाली शैली में लिखो.
• हेडिंग का इस्तेमाल करके, संगठन के बारे में साफ़ तौर पर जानकारी दें.
• बुलेट वाली सूचियों का इस्तेमाल करके, बहुत ज़्यादा टेक्स्ट को अलग-अलग हिस्सों में बांटें.
• इमेज और GIF का इस्तेमाल करें!

कोड स्टाइल

• ES5, ES6 या TypeScript में लिखा जा सकता है. हालांकि, शुरुआत में ही यह बता दें कि यह किस भाषा में लिखा गया है.
• Google की स्टाइल गाइड का पालन करें