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

समस्या की शिकायत करें सोर्स देखें

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

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

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

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

लिखने का तरीका

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

शीर्षक

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

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

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

  • टाइटल के लिए वाक्य केस का इस्तेमाल करें

    • हां: अपना फ़ाइल फ़ोल्डर सेट अप करें
    • नहीं: अपना Workspace खाता सेट अप करें

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

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

नाम

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

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

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

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

पेज का दायरा

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

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

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

विषय

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

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

    • हां: Basel का इस्तेमाल करके Java कोड बनाने के लिए, आपको JDK इंस्टॉल करना होगा.
    • MAYBE: अगर उपयोगकर्ताओं को Basel का इस्तेमाल करके Java कोड बनाना है, तो उन्हें JDK इंस्टॉल करना होगा.
    • नहीं: उपयोगकर्ता को Baज़ल के साथ Java कोड बनाने के लिए, JDK इंस्टॉल करना होगा.

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

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

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

कम समय

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

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

बेचैन

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

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

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

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

वीडियो की भाषा

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

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

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

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

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

फ़ाइल टाइप

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

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

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

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

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

सूचियां

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

प्लेसहोल्डर

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

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

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

विषय सूची

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

कोड

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

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

कोड ब्लॉक

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

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

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