बैजल दस्तावेज़ शैली गाइड

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

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

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

बेज़ल दस्तावेज़ में ये सिद्धांत लागू होने चाहिए:

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

लिखना

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

शीर्षक

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

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

    • हां: अनुमतियां
    • नहीं: अनुमतियों के बारे में कम शब्दों में जानकारी

  • शीर्षकों के लिए वाक्य केस का इस्तेमाल करें

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

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

    • हां: ग्राफ़ का क्रम सुरक्षित रखा जा रहा है
    • नहीं: ग्राफ़ के ऑर्डर को बनाए रखते हुए

नाम

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

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

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

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

पेज का दायरा

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

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

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

विषय

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

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

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

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

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

    • हां: जैसे-जैसे Bazel बेहतर होता जा रहा है, आपको इसके साथ काम करने के लिए, अपने कोड बेस को अपडेट करना चाहिए.
    • नहीं: Bazel बेहतर बनाया जा रहा है और हम Bazel में ऐसे बदलाव करेंगे कि कई बार बेज़ल में बदलाव किया जाएगा और उन्हें बेज़ल के उपयोगकर्ताओं को कुछ बदलाव करने होंगे.

क्षणिक

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

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

बेचैन

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

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

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

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

शैली

कारोबार के हिसाब से सही टेक्स्ट लिखें.

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

    • हां: ज़रूरी नियम
    • नहीं: एक अच्छा नियम क्या है?

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

फ़ॉर्मैटिंग

फ़ाइल टाइप

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

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

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

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

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

सूचियां

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

प्लेसहोल्डर

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

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

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

विषय सूची

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

कोड

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

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

कोड ब्लॉक

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

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

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