Bazel docs की स्टाइल गाइड

Bazel के दस्तावेज़ में योगदान देने के लिए धन्यवाद. यह दस्तावेज़, स्टाइल गाइड के तौर पर काम करता है. इससे आपको दस्तावेज़ लिखने में मदद मिलेगी. अगर इस गाइड में स्टाइल से जुड़े आपके सवालों के जवाब नहीं मिलते हैं, तो Google डेवलपर के दस्तावेज़ों के लिए बनी स्टाइल गाइड देखें.

सिद्धांत तय करना

Bazel के दस्तावेज़ों में इन सिद्धांतों का पालन किया जाना चाहिए:

• संक्षिप्त. कम से कम शब्दों का इस्तेमाल करें.
• साफ़ तौर पर. आसान भाषा का इस्तेमाल करें. पांचवीं कक्षा के छात्र-छात्राओं के पढ़ने के लेवल के हिसाब से, तकनीकी शब्दों का इस्तेमाल किए बिना लिखें.
• एक जैसा. दस्तावेज़ों में बार-बार आने वाले कॉन्सेप्ट के लिए, एक ही शब्द या वाक्यांश इस्तेमाल करें.
• सही. इस तरह से लिखें कि कॉन्टेंट ज़्यादा से ज़्यादा समय तक सही बना रहे. इसके लिए, समय के हिसाब से बदलने वाली जानकारी और आने वाले समय के लिए किए गए वादों से बचें.

लेखन

इस सेक्शन में, लिखने के लिए बुनियादी सुझाव दिए गए हैं.

हेडिंग

• पेज-लेवल की हेडिंग, H2 से शुरू होती हैं. (H1 हेडिंग का इस्तेमाल, पेज के टाइटल के तौर पर किया जाता है.)

• हेडर को जितना हो सके उतना छोटा रखें. इससे, वे रैप किए बिना विषय सूची में फ़िट हो जाते हैं.

  • हां: अनुमतियां
  • नहीं: अनुमतियों के बारे में संक्षिप्त नोट

• हेडिंग के लिए, अंग्रेज़ी के वाक्यों में पहला वर्ण बड़ा (अपर केस में) रखें

  • हां: अपना वर्कस्पेस सेट अप करें
  • नहीं: अपना वर्कस्पेस सेट अप करें

• हेडिंग को टास्क पर आधारित या ऐक्शन लेने लायक बनाने की कोशिश करें. अगर हेडिंग कॉन्सेप्ट पर आधारित हैं, तो वे समझने पर आधारित हो सकती हैं. हालांकि, उपयोगकर्ता के काम के हिसाब से लिखें.

  • हां: ग्राफ़ के क्रम को बनाए रखना
  • नहीं: ग्राफ़ के क्रम को बनाए रखने के बारे में

नाम

• प्रॉपर नाउन को कैपिटलाइज़ करें. जैसे, Bazel और Starlark.

  • हां: बिल्ड के आखिर में, Bazel, अनुरोध किए गए टारगेट प्रिंट करता है.
  • नहीं: बिल्ड के आखिर में, bazel, अनुरोध किए गए टारगेट प्रिंट करता है.

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

  • उदाहरण के लिए, अगर टर्मिनल पर कमांड जारी करने के बारे में लिखा जा रहा है, तो पेज पर टर्मिनल और कमांड लाइन, दोनों का इस्तेमाल न करें.

पेज का दायरा

• हर पेज का एक मकसद होना चाहिए. इसे पेज की शुरुआत में तय किया जाना चाहिए. इससे पाठकों को अपनी ज़रूरत की जानकारी तेज़ी से ढूंढने में मदद मिलती है.

  • हां: इस पेज पर, Windows पर Bazel इंस्टॉल करने का तरीका बताया गया है.
  • नहीं: (कोई शुरुआती वाक्य नहीं.)

• पेज के आखिर में, पाठक को बताएं कि उसे आगे क्या करना है. जिन पेजों पर कोई साफ़ तौर पर ऐक्शन नहीं है उनके लिए, मिलते-जुलते कॉन्सेप्ट, उदाहरण या एक्सप्लोर करने के अन्य तरीकों के लिंक शामिल किए जा सकते हैं.

विषय

Bazel के दस्तावेज़ों में, ऑडियंस मुख्य तौर पर उपयोगकर्ता होने चाहिए. यानी, वे लोग जो अपना सॉफ़्टवेयर बनाने के लिए Bazel का इस्तेमाल करते हैं.

• अपने पाठक को "आप" कहकर संबोधित करें. (अगर किसी वजह से "आप" का इस्तेमाल नहीं किया जा सकता, तो जेंडर-न्यूट्रल भाषा का इस्तेमाल करें. जैसे, वे.)

  • हां: Bazel का इस्तेमाल करके Java कोड बनाने के लिए, आपको JDK इंस्टॉल करना होगा.
  • शायद: Bazel का इस्तेमाल करके Java कोड बनाने के लिए, उपयोगकर्ताओं को JDK इंस्टॉल करना होगा.
  • नहीं: Bazel का इस्तेमाल करके Java कोड बनाने के लिए, उपयोगकर्ता को JDK इंस्टॉल करना होगा.

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

• "हम" का इस्तेमाल न करें. उपयोगकर्ता के दस्तावेज़ों में, कोई लेखक नहीं होता. बस लोगों को बताएं कि क्या किया जा सकता है.

  • हां: Bazel के अपडेट होने पर, आपको अपनी कोड बेस को अपडेट करना चाहिए, ताकि वह काम करता रहे.
  • नहीं: Bazel अपडेट हो रहा है. हम Bazel में ऐसे बदलाव करेंगे जो कभी-कभी काम नहीं करेंगे. इसके लिए, Bazel के उपयोगकर्ताओं को कुछ बदलाव करने होंगे.

Temporal

जहां तक हो सके, ऐसे शब्दों का इस्तेमाल न करें जो समय के हिसाब से बदलते हैं. जैसे, खास तारीखों (दूसरी तिमाही, 2022) का रेफ़रंस देना या "अभी", "फ़िलहाल" या "जल्द ही" कहना. ये शब्द जल्द ही पुराने हो जाते हैं और अगर यह आने वाले समय के लिए अनुमान है, तो यह गलत भी हो सकता है. इसके बजाय, वर्शन लेवल तय करें. जैसे, "Bazel X.x और इससे ऊपर के वर्शन, <सुविधा> के साथ काम करते हैं या GitHub पर समस्या का लिंक.

• हां: Bazel 0.10.0 या इसके बाद के वर्शन, रिमोट कैशिंग के साथ काम करते हैं.
• नहीं: Bazel जल्द ही रिमोट कैशिंग के साथ काम करेगा. ऐसा हो सकता है कि यह सुविधा, अक्टूबर 2017 में उपलब्ध हो जाए.

काल

• वर्तमान काल का इस्तेमाल करें. स्पष्टता के लिए, पास्ट या फ़्यूचर टेंस का इस्तेमाल सिर्फ़ तब करें, जब यह ज़रूरी हो.

  • हां: जब Bazel को ऐसी डिपेंडेंसी मिलती हैं जो इस नियम के मुताबिक नहीं होती हैं, तो वह गड़बड़ी का मैसेज दिखाता है.
  • नहीं: अगर Bazel को ऐसी डिपेंडेंसी मिलती है जो इस नियम के मुताबिक नहीं है, तो Bazel गड़बड़ी का मैसेज दिखाएगा.

• जहां तक हो सके, ऐक्टिव वॉइस (जिसमें कोई सब्जेक्ट, ऑब्जेक्ट पर ऐक्शन लेता है) का इस्तेमाल करें. पैसिव वॉइस (जिसमें किसी ऑब्जेक्ट पर सब्जेक्ट ऐक्शन लेता है) का इस्तेमाल न करें. आम तौर पर, ऐक्टिव वॉइस से वाक्य ज़्यादा साफ़ तौर पर समझ में आते हैं, क्योंकि इससे पता चलता है कि कौन ज़िम्मेदार है. अगर ऐक्टिव वॉइस का इस्तेमाल करने से वाक्य साफ़ तौर पर समझ में नहीं आता है, तो पैसिव वॉइस का इस्तेमाल करें.

  • हां: Bazel, X शुरू करता है और Y बनाने के लिए आउटपुट का इस्तेमाल करता है.
  • नहीं: X को Bazel शुरू करता है. इसके बाद, Y को आउटपुट की मदद से बनाया जाएगा.

टोन

बिज़नेस के हिसाब से सही टोन में लिखें.

• बोलचाल की भाषा का इस्तेमाल न करें. अंग्रेज़ी में इस्तेमाल होने वाले ऐसे वाक्यांशों का अनुवाद करना मुश्किल होता है जो सिर्फ़ अंग्रेज़ी में इस्तेमाल किए जाते हैं.

  • हां: अच्छे नियम सेट
  • नहीं: तो अच्छा नियम सेट क्या होता है?

• ज़्यादा औपचारिक भाषा का इस्तेमाल न करें. इस तरह से लिखें जैसे कि आप किसी ऐसे व्यक्ति को कॉन्सेप्ट के बारे में बता रहे हैं जिसे टेक्नोलॉजी के बारे में जानने में दिलचस्पी है, लेकिन उसे ज़्यादा जानकारी नहीं है.

फ़ॉर्मैटिंग

फ़ाइल टाइप

पढ़ने में आसानी के लिए, लाइनों को 80 वर्णों पर रैप करें. बड़े लिंक या कोड स्निपेट लंबे हो सकते हैं, लेकिन उन्हें नई लाइन से शुरू करना चाहिए. उदाहरण के लिए:

लिंक

• "यहां" या "नीचे" के बजाय, जानकारी देने वाले लिंक टेक्स्ट का इस्तेमाल करें. इस तरीके से, दस्तावेज़ को स्कैन करना आसान हो जाता है. साथ ही, यह स्क्रीन रीडर के लिए भी बेहतर होता है.

  • हां: ज़्यादा जानकारी के लिए, [Bazel इंस्टॉल करना] देखें.
  • नहीं: ज़्यादा जानकारी के लिए, [यहां] देखें.

• अगर हो सके, तो वाक्य को लिंक के साथ खत्म करें.

  • हां: ज़्यादा जानकारी के लिए, [लिंक] देखें.
  • नहीं: ज़्यादा जानकारी के लिए, [लिंक] देखें.

सूचियां

• किसी टास्क को चरणों में पूरा करने का तरीका बताने के लिए, क्रम से लगाई गई सूची का इस्तेमाल करें
• टास्क पर आधारित नहीं होने वाली चीज़ों की सूची बनाने के लिए, क्रम से नहीं लगाई गई सूची का इस्तेमाल करें. (हालांकि, सूची में किसी तरह का क्रम होना चाहिए. जैसे, वर्णमाला के क्रम में, अहमियत के हिसाब से वगैरह.)
• एक जैसी संरचना का इस्तेमाल करके लिखें. उदाहरण के लिए:
  1. सूची के सभी आइटम को वाक्य बनाएं.
  2. एक ही काल वाले वर्ब से शुरू करें.
  3. अगर फ़ॉलो करने के लिए चरण हैं, तो क्रम से लगाई गई सूची का इस्तेमाल करें.

प्लेसहोल्डर

• ऐसे वैरिएबल को दिखाने के लिए ऐंगल ब्रैकेट का इस्तेमाल करें जिन्हें उपयोगकर्ताओं को बदलना चाहिए. मार्कडाउन में, ऐंगल ब्रैकेट से पहले बैक स्लैश लगाएं: \<example\>.

  • हां: bazel help <command>: <command> के लिए मदद और विकल्प प्रिंट करता है
  • नहीं: bazel help command: मदद और विकल्प प्रिंट करता है "command" के लिए

• खास तौर पर, कोड के मुश्किल सैंपल के लिए, ऐसे प्लेसहोल्डर का इस्तेमाल करें जो कॉन्टेक्स्ट के हिसाब से सही हों.

विषय सूची

साइट पर अपने-आप जनरेट होने वाली विषय सूची का इस्तेमाल करें. मैन्युअल तरीके से विषय सूची न जोड़ें.

कोड

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

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

कोड ब्लॉक

• इसे छोटा रखें. कोड के सैंपल से, ज़रूरत से ज़्यादा या गैर-ज़रूरी सभी टेक्स्ट हटाएं.
• मार्कडाउन में, सैंपल की भाषा जोड़कर कोड ब्लॉक का टाइप तय करें.

```shell
...

• कमांड और आउटपुट को अलग-अलग कोड ब्लॉक में रखें.

इनलाइन कोड फ़ॉर्मैटिंग

• फ़ाइल के नाम, डायरेक्ट्री, पाथ, और कोड के छोटे-छोटे हिस्सों के लिए, कोड स्टाइल का इस्तेमाल करें.
• _इटैलिक_ , "कोट" या **बोल्ड** के बजाय, इनलाइन कोड स्टाइलिंग का इस्तेमाल करें.
  • हां: bazel help <command>: <command> के लिए मदद और विकल्प प्रिंट करता है
  • नहीं: bazel help command: मदद और विकल्प प्रिंट करता है "command" के लिए