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

समस्या की शिकायत करें सोर्स देखें Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

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

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

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

लेखन

इस सेक्शन में, लिखने से जुड़ी बुनियादी सलाह दी गई है.

हेडिंग

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

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

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

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

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

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

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

नाम

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

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

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

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

पेज स्कोप

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

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

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

विषय

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

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

    • हां: Bazel का इस्तेमाल करके Java कोड बनाने के लिए, आपको JDK इंस्टॉल करना होगा.
    • MAYBE: 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" के लिए सहायता और विकल्प दिखाता है