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

7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

सिद्धांत की परिभाषा

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

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

लेखन

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

शीर्षक

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

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

    • हां: अनुमतियां
    • नहीं: अनुमतियों के बारे में एक छोटा सा नोट

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

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

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

    • हां: ग्राफ़ के क्रम को बनाए रखना
    • नहीं: ग्राफ़ ऑर्डर के संरक्षण पर

नाम

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

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

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

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

पेज का दायरा

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

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

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

विषय

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

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

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

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

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

    • हां: Basel के अपडेट होने के बाद, आपको अपना कोड बेस अपडेट करना चाहिए, ताकि उसके साथ काम करता रहे.
    • नहीं: Basel को बेहतर बनाया जा रहा है और हम Ba बैंक

कम समय

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

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

बेचैन

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

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

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

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

टोन

कारोबार के लिहाज़ से अच्छे लहजे में लिखें.

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

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

  • बहुत ज़्यादा फ़ॉर्मल भाषा का इस्तेमाल न करें. ऐसे लिखो जिससे यह लगे कि आप किसी ऐसे व्यक्ति को सिद्धांत समझा रहे हैं जिसे टेक्नोलॉजी के बारे में जानकारी है, लेकिन उसे इसकी जानकारी नहीं है.

फ़ॉर्मैटिंग

फ़ाइल टाइप

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

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

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

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

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

सूचियां

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

प्लेसहोल्डर

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

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

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

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

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

कोड

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

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

कोड ब्लॉक

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

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

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