This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

प्रलेखन शैली अवलोकन

इस खंड के विषय लेखन शैली, सामग्री स्वरूपण, और संगठन, और कुबेरनेट्स प्रलेखन के लिए विशिष्ट Hugo अनुकूलन का उपयोग करने पर मार्गदर्शन प्रदान करते हैं।

1 - पृष्ठ सामग्री के प्रकार

Kubernetes दस्तावेज़ कई प्रकार की पृष्ठ सामग्री का पालन करता है:

  • अवधारणा (Concept)
  • कार्य (Task)
  • ट्यूटोरियल (Tutorial)
  • संदर्भ (Reference)

सामग्री अनुभाग

प्रत्येक पृष्ठ सामग्री प्रकार में Markdown टिप्पणियों और HTML शीर्षकों द्वारा परिभाषित कई अनुभाग होते हैं। आप heading शॉर्टकोड के साथ अपने पृष्ठ में सामग्री शीर्षक जोड़ सकते हैं। टिप्पणियाँ और शीर्षक पृष्ठ सामग्री प्रकारों की संरचना को बनाए रखने में मदद करते हैं।

पृष्ठ सामग्री अनुभागों को परिभाषित करने वाली Markdown टिप्पणियों के उदाहरण:

<!-- overview -->

<!-- body -->

अपने सामग्री पृष्ठों में सामान्य शीर्षक बनाने के लिए, heading शॉर्टकोड का उपयोग एक शीर्षक स्ट्रिंग के साथ करें।

शीर्षक स्ट्रिंग के उदाहरण:

  • whatsnext
  • prerequisites
  • objectives
  • cleanup
  • synopsis
  • seealso
  • options

उदाहरण के लिए, whatsnext शीर्षक बनाने के लिए, "whatsnext" स्ट्रिंग के साथ heading शॉर्टकोड जोड़ें:

## {{% heading "whatsnext" %}}

आप prerequisites शीर्षक को इस प्रकार घोषित कर सकते हैं:

## {{% heading "prerequisites" %}}

heading शॉर्टकोड एक स्ट्रिंग पैरामीटर की अपेक्षा करता है। शीर्षक स्ट्रिंग पैरामीटर i18n/<lang>/<lang>.toml फ़ाइलों में एक वेरिएबल के उपसर्ग (prefix) से मेल खाता है। उदाहरण के लिए:

i18n/en/en.toml:

[whatsnext_heading]
other = "What's next"

i18n/hi/hi.toml:

[whatsnext_heading]
other = "आगे क्या है"

सामग्री के प्रकार

प्रत्येक सामग्री प्रकार अनौपचारिक रूप से अपनी अपेक्षित पृष्ठ संरचना को परिभाषित करता है। सुझाए गए पृष्ठ अनुभागों के साथ पृष्ठ सामग्री बनाएँ।

अवधारणा (Concept)

एक अवधारणा पृष्ठ Kubernetes के कुछ पहलू की व्याख्या करता है। उदाहरण के लिए, एक अवधारणा पृष्ठ Kubernetes डिप्लॉयमेंट ऑब्जेक्ट का वर्णन कर सकता है और उस भूमिका की व्याख्या कर सकता है जो यह एक एप्लिकेशन के रूप में निभाता है जब इसे तैनात, स्केल और अपडेट किया जाता है। आमतौर पर, अवधारणा पृष्ठों में चरणों के अनुक्रम शामिल नहीं होते हैं, बल्कि इसके बजाय कार्यों या ट्यूटोरियल के लिंक प्रदान करते हैं।

एक नया अवधारणा पृष्ठ लिखने के लिए, /content/en/docs/concepts निर्देशिका की एक उप-निर्देशिका में एक Markdown फ़ाइल बनाएँ, जिसमें निम्नलिखित विशेषताएँ हों:

अवधारणा पृष्ठों को तीन अनुभागों में विभाजित किया गया है:

पृष्ठ अनुभाग
overview
body
whatsnext

overview और body अनुभाग अवधारणा पृष्ठ में टिप्पणियों के रूप में दिखाई देते हैं। आप heading शॉर्टकोड के साथ अपने पृष्ठ में whatsnext अनुभाग जोड़ सकते हैं।

प्रत्येक अनुभाग को सामग्री से भरें। इन दिशानिर्देशों का पालन करें:

  • H2 और H3 शीर्षकों के साथ सामग्री को व्यवस्थित करें।
  • overview के लिए, विषय के संदर्भ को एक एकल पैराग्राफ के साथ सेट करें।
  • body के लिए, अवधारणा की व्याख्या करें।
  • whatsnext के लिए, अवधारणा के बारे में अधिक जानने के लिए विषयों की एक बुलेटेड सूची (अधिकतम 5) प्रदान करें।

एनोटेशन एक अवधारणा पृष्ठ का एक प्रकाशित उदाहरण है।

कार्य (Task)

एक कार्य पृष्ठ दिखाता है कि एक एकल काम कैसे करना है, आमतौर पर चरणों का एक छोटा अनुक्रम देकर। कार्य पृष्ठों में न्यूनतम स्पष्टीकरण होता है, लेकिन अक्सर वैचारिक विषयों के लिंक प्रदान करते हैं जो संबंधित पृष्ठभूमि और ज्ञान प्रदान करते हैं।

एक नया कार्य पृष्ठ लिखने के लिए, /content/en/docs/tasks निर्देशिका की एक उप-निर्देशिका में एक Markdown फ़ाइल बनाएँ, जिसमें निम्नलिखित विशेषताएँ हों:

पृष्ठ अनुभाग
overview
prerequisites
steps
discussion
whatsnext

overview, steps, और discussion अनुभाग कार्य पृष्ठ में टिप्पणियों के रूप में दिखाई देते हैं। आप heading शॉर्टकोड के साथ अपने पृष्ठ में prerequisites और whatsnext अनुभाग जोड़ सकते हैं।

प्रत्येक अनुभाग के भीतर, अपनी सामग्री लिखें। निम्नलिखित दिशानिर्देशों का उपयोग करें:

  • न्यूनतम H2 शीर्षकों का उपयोग करें (दो अग्रणी # वर्णों के साथ)। अनुभाग स्वयं टेम्प्लेट द्वारा स्वचालित रूप से शीर्षक दिए जाते हैं।
  • overview के लिए, पूरे विषय के लिए संदर्भ सेट करने के लिए एक पैराग्राफ का उपयोग करें।
  • prerequisites के लिए, जब संभव हो बुलेट सूचियों का उपयोग करें। include के नीचे अतिरिक्त पूर्वापेक्षाएँ जोड़ना शुरू करें। डिफ़ॉल्ट पूर्वापेक्षाओं में एक चालू Kubernetes क्लस्टर शामिल है।
  • steps के लिए, क्रमांकित सूचियों का उपयोग करें।
  • चर्चा (discussion) के लिए, steps में कवर की गई जानकारी का विस्तार करने के लिए सामान्य सामग्री का उपयोग करें।
  • whatsnext के लिए, 5 विषयों तक की एक बुलेट सूची दें जिसे पाठक आगे पढ़ने में रुचि ले सकता है।

एक प्रकाशित कार्य विषय का उदाहरण Kubernetes API तक पहुँचने के लिए HTTP प्रॉक्सी का उपयोग करना है।

ट्यूटोरियल (Tutorial)

एक ट्यूटोरियल पृष्ठ दिखाता है कि एक लक्ष्य को कैसे प्राप्त किया जाए जो एक एकल कार्य से बड़ा है। आमतौर पर एक ट्यूटोरियल पृष्ठ में कई अनुभाग होते हैं, जिनमें से प्रत्येक में चरणों का एक अनुक्रम होता है। उदाहरण के लिए, एक ट्यूटोरियल एक कोड नमूने का पूर्वाभ्यास प्रदान कर सकता है जो Kubernetes की एक निश्चित विशेषता को दर्शाता है। ट्यूटोरियल में सतही स्तर की व्याख्याएँ शामिल हो सकती हैं, लेकिन गहरी व्याख्याओं के लिए संबंधित अवधारणा विषयों से लिंक करना चाहिए।

एक नया ट्यूटोरियल पृष्ठ लिखने के लिए, /content/en/docs/tutorials निर्देशिका की एक उप-निर्देशिका में एक Markdown फ़ाइल बनाएँ, जिसमें निम्नलिखित विशेषताएँ हों:

पृष्ठ अनुभाग
overview
prerequisites
objectives
lessoncontent
cleanup
whatsnext

overview, objectives, और lessoncontent अनुभाग ट्यूटोरियल पृष्ठ में टिप्पणियों के रूप में दिखाई देते हैं। आप heading शॉर्टकोड के साथ अपने पृष्ठ में prerequisites, cleanup, और whatsnext अनुभाग जोड़ सकते हैं।

प्रत्येक अनुभाग के भीतर, अपनी सामग्री लिखें। निम्नलिखित दिशानिर्देशों का उपयोग करें:

  • न्यूनतम H2 शीर्षकों का उपयोग करें (दो अग्रणी # वर्णों के साथ)। अनुभाग स्वयं टेम्प्लेट द्वारा स्वचालित रूप से शीर्षक दिए जाते हैं।
  • overview के लिए, पूरे विषय के लिए संदर्भ सेट करने के लिए एक पैराग्राफ का उपयोग करें।
  • prerequisites के लिए, जब संभव हो बुलेट सूचियों का उपयोग करें। डिफ़ॉल्ट रूप से शामिल लोगों के नीचे अतिरिक्त पूर्वापेक्षाएँ जोड़ें।
  • objectives के लिए, बुलेट सूचियों का उपयोग करें।
  • lessoncontent के लिए, क्रमांकित सूचियों और कथा सामग्री के मिश्रण का उपयोग करें जैसा कि उपयुक्त हो।
  • cleanup के लिए, कार्य पूरा करने के बाद क्लस्टर की स्थिति को साफ करने के चरणों का वर्णन करने के लिए क्रमांकित सूचियों का उपयोग करें।
  • whatsnext के लिए, 5 विषयों तक की एक बुलेट सूची दें जिसे पाठक आगे पढ़ने में रुचि ले सकता है।

एक प्रकाशित ट्यूटोरियल विषय का उदाहरण एक डिप्लॉयमेंट का उपयोग करके स्टेटलेस एप्लिकेशन चलाना है।

संदर्भ (Reference)

एक घटक उपकरण संदर्भ पृष्ठ एक Kubernetes घटक उपकरण के लिए वर्णन और फ्लैग विकल्प आउटपुट दिखाता है। प्रत्येक पृष्ठ घटक उपकरण आदेशों का उपयोग करके स्क्रिप्ट से उत्पन्न होता है।

एक उपकरण संदर्भ पृष्ठ में कई संभावित अनुभाग होते हैं:

पृष्ठ अनुभाग
synopsis
options
options from parent commands
examples
seealso

प्रकाशित उपकरण संदर्भ पृष्ठों के उदाहरण हैं:

आगे क्या है