शुरुआती जानकारी
कोडलैब एक इंटरैक्टिव ट्यूटोरियल होता है, जिसे मार्कडाउन सिंटैक्स में लिखा जाता है. हम अपने कोडलैब को blocklycodelabs.dev पर पब्लिश करते हैं. कोडलैब आपको ट्यूटोरियल का ज़्यादा दिलचस्प अनुभव देने के लिए आम भाषा, कोड सैंपल, और स्क्रीनशॉट का इस्तेमाल करता है. कोडलैब का टारगेट उपयोगकर्ता, कोड को पढ़ते समय उसे चला रहा है.
कोडलैब लिखना, समुदाय में योगदान देने का एक बेहतरीन तरीका है. यह अपनी जानकारी शेयर करने और उसी समस्या से जूझ रहे अगले डेवलपर की ज़िंदगी आसान बनाने का एक तरीका है.
एक बेहतरीन कोडलैब (कोडलैब) कैसा होता है?
एक बेहतरीन कोडलैब फ़ोकस किया जाता है और उसे आसानी से पढ़ा जा सकता है. इससे उपयोगकर्ता को साफ़ तौर पर पता चलता है कि वे क्या बनाएंगे और क्या सीखेंगे. साथ ही, यह उपयोगकर्ता को किसी खास टास्क को पूरा करने के लिए कोड लिखने और समझने के बारे में बताता है.
प्रोसेस
अगर आपके पास कोडलैब के लिए कोई आइडिया है, तो ब्लॉकली-सैंपल डेटा स्टोर करने की जगह में सुविधा का अनुरोध करके हमें इस बारे में बताएं. कोडलैब में यह जानकारी शामिल करें कि आपको क्या पढ़ाना है और क्या बनाना है. हम आइडिया पर चर्चा करेंगे और उसे बेहतर बनाएंगे. इसके बाद, उसे लिखें और उसके लिए पुल अनुरोध सबमिट करें. इसकी समीक्षा होने के बाद, ब्लॉकली टीम का कोई सदस्य इसे पब्लिश कर देगा.
लेखन युक्तियां
इस पेज के बाकी हिस्से में सलाह और सवाल हैं. ये आपको कोडलैब लिखने में मदद करेंगे.
तकनीकी लेखन की बुनियादी जानकारी के लिए तकनीकी राइटिंग One देखें.
दर्शक
- टारगेट रीडर कौन है?
- ब्लॉकली का इस्तेमाल करने के बारे में उन्हें पहले से क्या पता है?
- वे क्या सीखने की कोशिश कर रहे हैं?
सेटअप
- कोड चलाने के लिए, उपयोगकर्ता को कम से कम कितना सेटअप पूरा करना होता है?
अगर मददगार हो, तो examples डायरेक्ट्री में स्टार्टर कोड और पूरा कोड पब्लिश किया जा सकता है.
बनावट
किसी भी अन्य लेखन की तरह, आउटलाइन से शुरुआत करें. यह ज़्यादातर कोडलैब के लिए सही स्ट्रक्चर है:
- बुनियादी जानकारी
- आप इन चीज़ों के बारे में जानेंगे
- आप क्या बनाएंगे
- आपको क्या जानने की आवश्यकता है
- सेटअप के लिए निर्देश
- पहला चरण: [टाइटल यहां दिखेगा]
- पूरी जानकारी/प्रेरणा
- कोड सैंपल
- अनुमानित नतीजे
- (ज़रूरी नहीं) ज़्यादा जानकारी
- ...
- दसवां चरण: [टाइटल यहां दिखेगा]
- खास जानकारी
- आपने यह सीखा
- आपने क्या बनाया
- अन्य संसाधन
- पूरे हो चुके कोड का लिंक (अगर उपलब्ध है)
आपके पास 10 से ज़्यादा चरण पूरे करने का विकल्प है, लेकिन 20 चरणों को पूरा करने के बाद, आपको इसे दो कोडलैब में बांटना चाहिए.
लिखने की शैली
- बातचीत वाले तरीके का इस्तेमाल करें.
- संगठन में साफ़ तौर पर जानकारी देने के लिए हेडिंग का इस्तेमाल करें.
- टेक्स्ट के छोटे-छोटे हिस्सों को तोड़ने के लिए बुलेट वाली सूचियों का इस्तेमाल करें.
- इमेज और GIF का इस्तेमाल करें!
कोड स्टाइल
- ES5, ES6 या टाइपस्क्रिप्ट में मैसेज लिखा जा सकता है, लेकिन पाठक को इसकी शुरुआत में बताएं.
- Google की स्टाइल गाइड का पालन करें