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

किसी समस्या की शिकायत करें सोर्स देखें Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

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

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

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

लेखन

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

शीर्षक

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

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

    • हां: अनुमतियां
    • नहीं: अनुमतियों के बारे में खास जानकारी

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

    • हां: अपना Workspace खाता सेट अप करें
    • नहीं: अपना Workspace खाता सेट अप करना

  • हेडलाइन को टास्क के हिसाब से या कार्रवाई करने लायक बनाएं. अगर हेडिंग कॉन्सेप्ट के हिसाब से हैं, तो हो सकता है कि वे समझने के लिए हों. हालांकि, उन्हें इस हिसाब से लिखें कि उपयोगकर्ता क्या करता है.

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

नाम

  • Bazel और Starlark जैसे व्यक्तिवाचक संज्ञाओं को कैपिटल लेटर में लिखें.

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

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

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

पेज का दायरा

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

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

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

विषय

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

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

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

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

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

    • हां: 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 help command: "command" के लिए सहायता और विकल्प दिखाता है

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

कॉन्टेंट का टेबल

साइट पर अपने-आप जनरेट हुए टीओसी का इस्तेमाल करें. मैन्युअल रूप से बनाए गए कॉन्टेंट का टेबल ऑफ़ कॉन्टेंट न जोड़ें.

कोड

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

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

कोड ब्लॉक

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

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

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