बेज़ल के दस्तावेज़ पर योगदान देने के लिए धन्यवाद. यह तुरंत दस्तावेज़ स्टाइल गाइड का इस्तेमाल करें. स्टाइल से जुड़े सवालों के लिए इस गाइड में दिए गए सवालों के जवाब देने के लिए, Google Developers की डॉक्यूमेंटेशन स्टाइल गाइड.
सिद्धांत की परिभाषा
बेज़ल दस्तावेज़ों में इन सिद्धांतों का पालन होना चाहिए:
- कम शब्दों में. कम से कम शब्दों का इस्तेमाल करें.
- मिटाएं. आसान भाषा का इस्तेमाल करें. पांचवीं क्लास के लिए, कठिन शब्दावली का इस्तेमाल किए बिना लिखें पढ़ने का स्तर.
- एक ही तरह से. दोहराए जाने वाले कॉन्सेप्ट के लिए, एक जैसे शब्दों या वाक्यांशों का इस्तेमाल करें दस्तावेज़ों में मौजूद जानकारी मिलेगी.
- सही. इस तरह लिखें कि कॉन्टेंट उतने समय तक सही रहे ऐसा करने के लिए, समय पर आधारित जानकारी और आने वाले समय के वादों से बचें.
लेखन
इस सेक्शन में, लिखने से जुड़ी बुनियादी सलाह दी गई हैं.
शीर्षक
- पेज-लेवल की हेडिंग H2 से शुरू होती हैं. (H1 हेडिंग का इस्तेमाल पेज के टाइटल के तौर पर किया जाता है.)
हेडर को जितना हो सके उतना छोटा बनाएं. इस तरह से वे टीओसी में फ़िट हो जाते हैं बिना रैप किए.
- हां: अनुमतियां
- नहीं: अनुमतियों के बारे में एक छोटा सा नोट
टाइटल के लिए वाक्य केस का इस्तेमाल करें
- हां: अपना फ़ाइल फ़ोल्डर सेट अप करें
- नहीं: अपना Workspace खाता सेट अप करें
हेडिंग को टास्क के हिसाब से या कार्रवाई करने लायक बनाने की कोशिश करें. अगर शीर्षक सैद्धांतिक तरीके से दिए गए हैं, यह समझ पर आधारित हो सकता है, लेकिन उपयोगकर्ता जो कुछ करता है, उसे लिखें.
- हां: ग्राफ़ का क्रम बनाए रखना
- नहीं: ग्राफ़ ऑर्डर के संरक्षण पर
नाम
व्यक्तिवाचक संज्ञाओं को कैपिटल लेटर में रखें, जैसे कि बेज़ल और स्टारलार्क.
- हां: बिल्ड के आखिर में, Basel का अनुरोध किए गए टारगेट को प्रिंट करता है.
- नहीं: बिल्ड के आखिर में, बेज़ल, अनुरोध किए गए टारगेट को प्रिंट करता है.
इसे एक जैसा रखें. मौजूदा कॉन्सेप्ट के लिए नए नाम न जोड़ें. जगह लागू हो, तो शब्दावली.
- उदाहरण के लिए, अगर आप किसी टर्मिनल, पेज पर टर्मिनल और कमांड लाइन दोनों का इस्तेमाल न करें.
पेज का दायरा
हर पेज का एक मकसद होना चाहिए और उसे शुरुआत. इससे लोगों को अपनी ज़रूरत की चीज़ें जल्दी खोजने में मदद मिलती है.
- हां: इस पेज में Windows पर Basel को इंस्टॉल करने का तरीका बताया गया है.
- नहीं: (शुरुआती वाक्य नहीं.)
पेज के आखिर में, पाठक को बताएं कि आगे क्या करना है. उन पेजों के लिए जहां कोई स्पष्ट कदम नहीं है, आप मिलते-जुलते अवधारणाओं के लिंक शामिल कर सकते हैं, या एक्सप्लोरेशन के अन्य तरीके शामिल होते हैं.
विषय
Basel के दस्तावेज़ में, ऑडियंस मुख्य रूप से उपयोगकर्ता होनी चाहिए—इनका इस्तेमाल करने वाले लोग Basel को अपना सॉफ़्टवेयर बनाने के लिए कहा गया.
अपने पाठक को "आप" के तौर पर बोलें. (अगर किसी वजह से "आप" का इस्तेमाल नहीं किया जा सकता, ऐसी भाषा का इस्तेमाल करें जिसमें लिंग के आधार पर भेदभाव न हो, जैसे कि वे.)
- हां: Basel का इस्तेमाल करके Java कोड बनाने के लिए, आपको JDK इंस्टॉल करना होगा.
- MAYBE: अगर उपयोगकर्ताओं को Basel का इस्तेमाल करके Java कोड बनाना है, तो उन्हें JDK इंस्टॉल करना होगा.
- नहीं: उपयोगकर्ता के लिए, ताकि वे Java कोड बना सकें बेज़ल, उसे JDK इंस्टॉल करना होगा.
अगर आपकी ऑडियंस बैज के सामान्य उपयोगकर्ता नहीं हैं, तो पेज की शुरुआत में या सेक्शन में जोड़ें. दूसरे दर्शक शामिल हो सकते हैं मेंटेनर, योगदान देने वाले, प्रवासी या दूसरी भूमिकाएं.
"हम" शब्द का इस्तेमाल करने से बचें. उपयोगकर्ता दस्तावेज़ों में, कोई लेखक नहीं है; बस लोगों को बताओ कि किया जा सकता है.
- हां: Basel के प्लैटफ़ॉर्म में बदलाव होने पर, आपको अपना कोड बेस अपडेट करना चाहिए, ताकि साथ काम करता है.
- नहीं: Basel को बेहतर बनाया जा रहा है और हम Basel में बदलाव करेंगे, जो कि समय के साथ 'ठीक किया गया' के तौर पर सेट किए गए समय का इस्तेमाल नहीं किया जा सकेगा. साथ ही, बैज का इस्तेमाल करने वाले लोगों को कुछ बदलाव करने होंगे.
कम समय
जहां तक हो सके, ऐसे शब्दों का इस्तेमाल करने से बचें जो समय के हिसाब से सटीक होते हैं, जैसे कि ख़ास तारीखें (Q2 2022) या "अभी", "फ़िलहाल" या "जल्द ही" बताएं. ये गोते हैं पुरानी हो जाती है और भविष्य का कोई प्रोजेक्शन होने पर यह गलत भी हो सकती है. इसके बजाय, इसके बजाय, वर्शन लेवल सेट करें. जैसे, "Ba" X.x और उसके बाद के वर्शन पर काम करता है <feature> या GitHub से जुड़ी समस्या का लिंक दिया जा सकता है.
- हां: Basel 0.10.0 या उसके बाद वाले वर्शन पर काम करता है रिमोट कैशिंग.
- नहीं: Basel जल्द ही रिमोट की सुविधा का इस्तेमाल करेगा कैश मेमोरी में सेव किया जाएगा.
बेचैन
वर्तमान काल का इस्तेमाल करें. जब तक ज़रूरी न हो, पुराने या भविष्य के काल से बचें आसान भाषा में समझेंगे.
- हां: Basel की वजह से गड़बड़ी का मैसेज आता है ऐसी डिपेंडेंसी ढूंढता है जो इस नियम का पालन नहीं करती हैं.
- नहीं: अगर Baज़ल को ऐसी डिपेंडेंसी मिलती है जो इस नियम के अनुरूप नहीं है, तो बेज़ल एक गड़बड़ी जारी करेगा.
जब हो सके, ऐक्टिव वॉइस का इस्तेमाल करें. ऐसा तब करें, जब कोई व्यक्ति किसी ऑब्जेक्ट पर कार्रवाई कर रहा हो पैसिव वॉइस (जब किसी व्यक्ति या ऑब्जेक्ट पर, किसी ऑब्जेक्ट पर कार्रवाई की जाती है). आम तौर पर, ऐक्टिव वॉइस में वाक्यों को समझने में आसानी होती है, क्योंकि इससे पता चलता है कि ज़िम्मेदार कौन है. अगर आपने ऐक्टिव वॉइस का इस्तेमाल करने से साफ़ आवाज़ नहीं आती. पैसिव वॉइस का इस्तेमाल करें.
- हां: Baज़र, X शुरू करता है और Y तक बनाने के लिए आउटपुट.
- नहीं: X को Basel ने शुरू किया और फिर इसके बाद, आउटपुट की मदद से Y बनाया जाएगा.
टोन
कारोबार के लिहाज़ से अच्छे लहजे में लिखें.
आम बोलचाल की भाषा का इस्तेमाल न करें. ऐसे वाक्यांशों का अनुवाद करना कठिन है, जो ख़ास तौर पर अंग्रेज़ी भाषा के लिए.
- हां: अच्छे नियमसेट
- नहीं: तो एक अच्छा नियम-सेट क्या है?
ज़्यादा औपचारिक भाषा का इस्तेमाल करने से बचें. ऐसे लिखें जैसे कि आप किसी ऐसे व्यक्ति के लिए एक विचार है जिसे टेक्नोलॉजी के बारे में जानकारी तो है, लेकिन उसके बारे में कोई जानकारी नहीं है.
फ़ॉर्मैटिंग
फ़ाइल टाइप
आसानी से पढ़ा जा सके, इसके लिए लाइनों को 80 वर्णों तक रखें. लंबे लिंक या कोड स्निपेट लंबा हो सकता है, लेकिन किसी नई लाइन पर शुरू होना चाहिए. उदाहरण के लिए:
लिंक
"यहां" के बजाय, जानकारी देने वाले लिंक टेक्स्ट का इस्तेमाल करें या "नीचे" शामिल है. यह तरीका से दस्तावेज़ को स्कैन करना आसान हो जाता है और यह स्क्रीन रीडर के लिए बेहतर है.
- हां: ज़्यादा जानकारी के लिए, [Bazel इंस्टॉल किया जा रहा है] देखें.
- नहीं: ज़्यादा जानकारी के लिए [यहां] देखें.
अगर हो सके, तो लिंक का इस्तेमाल करके वाक्य के आखिर में जाएं.
- हां: ज़्यादा जानकारी के लिए, [link] देखें.
- नहीं: ज़्यादा जानकारी के लिए [link] देखें.
सूचियां
- किसी टास्क को पूरा करने के तरीके के बारे में बताने के लिए क्रम से लगाई गई सूची का इस्तेमाल करें
- उन चीज़ों को लिस्ट करने के लिए बिना क्रम वाली सूची का इस्तेमाल करें जो टास्क के हिसाब से नहीं हैं. (यहां आपको फिर भी, एक क्रम में हो. जैसे, वर्णमाला, महत्व वगैरह.)
- समानांतर संरचना के साथ लिखें. जैसे:
- आइटम की सभी सूची में वाक्य बनाएं.
- एक ही काल की क्रियाओं से शुरुआत करें.
- अगर पालन करना है, तो क्रम वाली सूची का इस्तेमाल करें.
प्लेसहोल्डर
ऐंगल ब्रैकेट का इस्तेमाल करके यह बताएं कि उपयोगकर्ताओं को किस वैरिएबल को बदलना चाहिए. Markdown में बैक स्लैश से ऐंगल ब्रैकेट को हटाएं:
\<example\>.- हां:
bazel help <command>: प्रिंट<command>के लिए सहायता और विकल्प - नहीं: बेज़ल सहायता कमांड: प्रिंट सहायता और "निर्देश" के लिए विकल्प
- हां:
खास तौर पर, मुश्किल कोड सैंपल के लिए प्लेसहोल्डर का इस्तेमाल करें मिलता है.
कॉन्टेंट का टेबल
साइट पर काम करने वाले अपने-आप जनरेट हुए टीओसी का इस्तेमाल करें. मैन्युअल टीओसी न जोड़ें.
कोड
कोड सैंपल डेवलपर के हैं सबसे अच्छे दोस्त. शायद आपको पता है कि इन्हें कैसे लिखना है लेकिन यहां कुछ सलाह दी गई है.
अगर आपको कोड के किसी छोटे स्निपेट का रेफ़रंस देना है, तो उसे किसी वाक्य में जोड़ा जा सकता है. अगर आपको पाठक को कोड इस्तेमाल करने देना है, जैसे कि किसी निर्देश को कॉपी करना, तो कोड का इस्तेमाल करें ब्लॉक.
कोड ब्लॉक
- ट्रेलर को छोटा रखें. कोड से सभी ग़ैर-ज़रूरी या ग़ैर-ज़रूरी टेक्स्ट हटाएं सैंपल.
- Markdown में सैंपल की भाषा जोड़कर, कोड ब्लॉक का टाइप तय करें.
```shell
...
- कमांड और आउटपुट को अलग-अलग कोड ब्लॉक में अलग-अलग करें.
इनलाइन कोड फ़ॉर्मैटिंग
- फ़ाइल नाम, डायरेक्ट्री, पाथ, और कोड के छोटे हिस्सों के लिए, कोड स्टाइल का इस्तेमाल करें.
- इटैलिक, "कोट", और इनलाइन कोड स्टाइल का इस्तेमाल करें या बोल्ड करें.
- हां:
bazel help <command>: प्रिंट<command>के लिए सहायता और विकल्प - नहीं: बेज़ल सहायता कमांड: प्रिंट सहायता और "निर्देश" के लिए विकल्प
- हां: