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 और इसके बाद के वर्शन में <feature> काम करती है" या 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" के लिए