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 में कुछ बदलाव करेंगे.

कम से कम

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

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

बेचैन

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

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

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

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

टोन

बिज़नेस फ़्रेंडली टोन में लिखें.

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

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

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

फ़ॉर्मैट करना

फ़ाइल टाइप

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

लिंक

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

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

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

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

सूचियां

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

प्लेसहोल्डर

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

  • हां: bazel help <command>: <command> के लिए प्रिंट सहायता और विकल्प
  • नहीं: bazel सहायता कमांड: प्रिंट से जुड़ी सहायता और "कमांड" के विकल्प

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

विषय सूची

अपने-आप जनरेट हुए टीओसी का इस्तेमाल करें जो साइट के साथ काम करता हो. टीओसी को मैन्युअल तौर पर न जोड़ें.

कोड

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

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

कोड ब्लॉक

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

```shell
...

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

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

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