कोडलैब लिखना

परिचय

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

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

कोडलैब को बेहतरीन बनाने के लिए क्या करना चाहिए?

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

प्रोसेस

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

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

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

तकनीकी लेखन के बारे में कम शब्दों में जानने के लिए, तकनीकी लेखन के बारे में बुनियादी जानकारी देखें.

ऑडियंस

• टारगेट रीडर कौन है?
• Blockly का इस्तेमाल करने के बारे में उन्हें पहले से क्या पता है?
• वे क्या सीखना चाहते हैं?

सेटअप

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

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

बनावट

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

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

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

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

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

कोड स्टाइल

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