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 वर्णों पर रैप करें. लंबे लिंक या कोड स्निपेट, 80 वर्णों से ज़्यादा हो सकते हैं. हालांकि, इन्हें नई लाइन से शुरू किया जाना चाहिए. उदाहरण के लिए:

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

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

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

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

सूचियां

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

प्लेसहोल्डर

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

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

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

विषय सूची

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

कोड

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

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

कोड ब्लॉक

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

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

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