बुरी सलाह: तकनीकी दस्तावेज कैसे लिखें? भाग तीन और अंतिम

उपयोगकर्ताओं के लिए तकनीकी दस्तावेज लिखने के लिए युक्तियाँ।
भाग 3 (अंतिम)

हमारे तकनीकी लेखक आंद्रेई स्टारोवितोव के मैनुअल का निष्कर्ष, जो आपके उपयोगकर्ता प्रलेखन को आसान और अधिक समझने में मदद करेगा।



इस बार हम और अधिक विस्तार से विचार करेंगे:

• वैचारिक विषय (अवधारणा पृष्ठ);
• संदर्भ विषय (संदर्भ पृष्ठ);
• ऐसे विषय जो किसी समस्या को हल करने का तरीका बताते हैं (समस्या निवारण पृष्ठ);
• स्क्रीनशॉट कहाँ और कैसे उपयोग करें;
• और अंग्रेजी में प्रलेखन लिखने वालों के लिए भी कुछ सुझाव दें।

पिछले भाग: प्रलेखन और स्थानीयकरण के लिए हमारा दृष्टिकोण; प्रलेखन युक्तियाँ भाग 1 और भाग 2 ।

वैचारिक विषय (अवधारणा पृष्ठ)

ऐसे विषयों की आवश्यकता होती है जो उपयोगकर्ताओं को अतिरिक्त तकनीकी जानकारी प्रदान करते हैं और जिससे कार्य विषय को अधिभार नहीं दिया जाता है।

कृपया ध्यान दें कि उनमें बिल्कुल अतिरिक्त जानकारी होनी चाहिए, लेकिन समस्या को हल करने का तरीका नहीं।

वैचारिक विषयों का उपयोग करने के लिए अच्छा है:

• बताओ कि एक विशेष प्रक्रिया कैसे काम करती है;
• वर्णन करें कि उत्पाद के इस संस्करण में कौन सी नई सुविधाएँ जोड़ी गईं;
• उपयोगकर्ता को अतिरिक्त जानकारी प्रदान करें जो उसे निर्णय लेने में मदद करेगा;
• बताएं कि आपके एप्लिकेशन में उपयोगकर्ता क्या कर सकता है।

उदाहरण के लिए, "वर्चुअल मशीन के बारे में" विषय यह बता सकता है कि यह क्या है और यह कैसे काम करता है। लेकिन इस विषय में वर्चुअल मशीन बनाने के निर्देश नहीं होने चाहिए - इसे कार्य विषय में वर्णित किया जाना चाहिए।

इस प्रकार, एक अनुभवी उपयोगकर्ता, कार्य विषय को पढ़ते समय, शिकायत नहीं करेगा: "आप मुझे क्यों पेंट करते हैं, यह क्या है, मुझे पहले से ही पता है ..."। और जो नहीं जानते हैं उन्हें एक वैचारिक विषय का लिंक दिखाई देगा और पढ़ा जाएगा।

आमतौर पर, वैचारिक विषय शीर्ष के साथ शुरू होते हैं:

• "(कुछ) के बारे में" ("वर्चुअल मशीन के बारे में");
• "क्या है ...?" ("वर्चुअल मशीन क्या है?");
• "यह कैसे काम करता है (कुछ)?" ("वर्चुअल मशीन कैसे काम करता है?");
• "वर्चुअल मशीन मूल बातें समझना", आदि।

यहाँ अंग्रेजी प्रलेखन से एक वैचारिक विषय का एक उदाहरण है:



संदर्भ विषय (संदर्भ पृष्ठ) :

इस तरह के विषय विभिन्न संदर्भ जानकारी का वर्णन करते हैं जो उपयोगकर्ता को संदर्भित कर सकता है यदि आवश्यक हो।

ऐसे विषयों के अच्छे उदाहरण हैं:

• गाइड के अंत में "शब्दावली";
• एक विषय जिसमें आप वर्णन करते हैं कि मेनू में कौन से आइटम उपलब्ध हैं और वे क्या करते हैं, कार्यक्रम के साथ काम करते समय आप कौन से कीबोर्ड का उपयोग कर सकते हैं, टास्कबार पर कौन से आइकन उपलब्ध हैं, आदि।

यहाँ एक विषय का एक उदाहरण है जो GUI आइकन का वर्णन करता है:



विषय जो किसी समस्या को हल करने का वर्णन करते हैं (समस्या निवारण पृष्ठ)


ऐसे विषय उपयोगकर्ता को एक बाधा को दूर करने या किसी समस्या को हल करने में मदद करते हैं। समस्या निवारण विषय में निम्न परिदृश्य हो सकते हैं:

• उपयोगकर्ता के पास एक समस्या है और इसे हल करना चाहता है। उदाहरण के लिए, "मेरा USB डिवाइस वर्चुअल मशीन में काम नहीं करता है"।
• उपयोगकर्ता ने कुछ करने की कोशिश की और असफल रहा। उदाहरण के लिए, "मैं समानताएं डेस्कटॉप को सक्रिय नहीं कर सकता" ("मैं समानताएं डेस्कटॉप को सक्रिय नहीं कर सकता")।
• कुछ शर्त या शर्त है जिसे उपयोगकर्ता बदलना चाहता है। उदाहरण के लिए, "विंडोज धीमा है" ("विंडोज लगता है धीमी")।

समस्या निवारण क्या है और क्या नहीं :

यदि उपयोगकर्ता कुछ करना चाहता है, लेकिन नहीं जानता कि कैसे, यह समस्या निवारण में नहीं, बल्कि कार्य विषय में वर्णित किया जाना चाहिए।

समस्या निवारण का अर्थ है कि उपयोगकर्ता ने कुछ करने की कोशिश की (कार्य विषय के निर्देशों के अनुसार), लेकिन कुछ समस्या थी, और उपयोगकर्ता यह नहीं जानता कि इसे कैसे हल किया जाए।

उदाहरण के लिए, एक विषय जो अतिथि ऑपरेटिंग सिस्टम में बाहरी ड्राइव का उपयोग करने का वर्णन करता है, एक कार्य विषय है।

और विषय जो संभावित समस्याओं का वर्णन करता है - "मुझे हार्ड डिस्क कनेक्ट करने में समस्या हो रही है" - एक समस्या निवारण विषय है। इसकी सामग्री का अर्थ है कि उपयोगकर्ता ने निर्देशों का पालन किया था, लेकिन किसी कारण से वह सफल नहीं हुआ।

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

उदाहरण के लिए, उस विषय के अंत में, जो कीबोर्ड शॉर्टकट को बदलने का वर्णन करता है, आप इसमें जोड़ सकते हैं: "कुछ प्रमुख संयोजनों को संपादित या हटाया नहीं जा सकता है"।

समस्या निवारण विषय

आमतौर पर, समस्या निवारण विषयों में कार्य विषयों के समान एक संरचना होती है।

इनमें शामिल हैं:

• शीर्षक ("शीर्षक")
• परिचयात्मक भाग ("परिचय")
• परिचयात्मक वाक्यांश, जिसके बाद गिने हुए चरण या आवश्यक जानकारी ("स्टेप हेडिंग") शुरू होती है
• एक समस्या को हल करने के लिए आवश्यक जानकारी ("समाधान के लिए कदम")
• अंतिम भाग ("आउट्रो")

शीर्षक (पेज शीर्षक)

यह अच्छा है जब समस्या निवारण विषय का शीर्षलेख उपयोगकर्ता की पहली-व्यक्ति समस्या को व्यक्त करता है। उदाहरण के लिए:

• "मैं समानताएं डेस्कटॉप को सक्रिय नहीं कर सकता" ("मैं समानताएं डेस्कटॉप को सक्रिय नहीं कर सकता")
• "विंडोज धीमा है" ("विंडोज लगता है धीमी")
• "एक संदेश कहते हैं, 'कोई वर्चुअल मशीन का पता नहीं चला'

यदि आप अंग्रेजी में दस्तावेज़ लिख रहे हैं, तो आपको शीर्षक में कैपिटल-स्टाइल कैपिटलाइज़ेशन का उपयोग करना चाहिए (कैपिटलाइज़ेशन के लिए, लेख के अंत में विवरण देखें):

अधिकार: मेरा USB डिवाइस काम नहीं कर रहा है

गलत: मेरा USB डिवाइस काम नहीं कर रहा है

परिचय (परिचय)

शीर्षक के तुरंत बाद, उपयोगकर्ताओं को उन जानकारी प्रदान करें, जिन्हें उन्हें पहले जानना आवश्यक है।

उदाहरण के लिए:

• समस्या का सबसे संभावित कारण बताएं। यदि कई कारण हो सकते हैं, तो सभी संभव का वर्णन करें।
• कभी-कभी आप सामान्य शब्दों में वर्णन कर सकते हैं कि किसी समस्या को हल करने के लिए क्या करने की आवश्यकता है। यह सामान्य रूप से है - समाधान के चरणों में विस्तृत निर्देश दिए जाने चाहिए।

परिचयात्मक वाक्यांश (स्टेप हैडिंग)

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

यदि समस्या का समाधान अनुक्रमिक क्रियाओं की एक श्रृंखला है:

ऐसे मामलों में, परिचयात्मक वाक्यांश समान सिद्धांतों के अनुसार किया जाना चाहिए जैसे कि कार्य विषयों (सुझावों का दूसरा भाग देखें), अर्थात्, कार्य सूत्रीकरण के समान शब्दों का उपयोग करें।

उदाहरण के लिए, आप एक समस्या निवारण विषय लिखते हैं जिसमें आप समझाते हैं कि उपयोगकर्ता वर्चुअल मशीन कॉन्फ़िगरेशन को क्यों नहीं खोल सकता (मेनू आइटम को धूसर कर दिया गया है और निष्क्रिय है:

शीर्षक: "मैं वर्चुअल मशीन सेटिंग्स नहीं खोल सकता"

परिचय: "यदि आप वर्चुअल मशीन सेटिंग्स नहीं खोल सकते हैं (मेनू आइटम ग्रे हो गया है), तो सबसे संभावित कारण यह है कि वर्चुअल मशीन बंद नहीं हुई है।"

इसके अलावा, परिचयात्मक वाक्यांश: "आभासी मशीन की सेटिंग खोलने के लिए:" (इस शब्द का उपयोग इस वाक्यांश में किया जाता है जैसे कि कार्य किए जाने के निर्माण में)

और फिर चरण हैं - 1) सुनिश्चित करें कि मशीन बंद है। यदि यह काम करता है, तो वहां और वहां क्लिक करें। 2) फिर ऐसा करें।

यदि समस्या के कई समाधान हैं:

ऐसे मामलों में, परिचयात्मक वाक्यांश में शब्द शामिल होने चाहिए:

- "इन समाधानों का प्रयास करें",
- "निम्नलिखित प्रयास करें",
- "यह सुनिश्चित करें कि", आदि।

अंग्रेजी प्रलेखन के कुछ उदाहरण इस प्रकार हैं:

पृष्ठ का शीर्षक: मैं समानताएं डेस्कटॉप को सक्रिय नहीं कर सकता
कार्य कवर: जाँच करने के लिए चीजों की एक सूची
चरण शीर्षक: यदि आपको समानताएं डेस्कटॉप को सक्रिय करने में समस्या हो रही है, तो सुनिश्चित करें कि ...

पृष्ठ का शीर्षक: विंडोज लगता है धीमा
टास्क कवर: कोशिश करने के लिए चीजों की एक सूची
चरण शीर्षक: यदि Windows प्रदर्शन धीमा लगता है, तो निम्न प्रयास करें ...

पृष्ठ का शीर्षक: एक संदेश कहता है "कोई मैक कनेक्टेड नहीं"
टास्क कवर्स: कई चीजों को जांचना या आज़माना
स्टेप हेडिंग: यदि आप अपने मैक को मैक की सूची में नहीं देखते हैं

समस्या को हल करने के लिए आवश्यक जानकारी (समाधान के कदम)

इस खंड में वह सब कुछ शामिल है जो उपयोगकर्ता को जानना और / या शुरू करना है।

यदि कई समाधान हैं:
ऐसे मामलों में, गोलियों का उपयोग करके प्रत्येक विधि का वर्णन करें (युक्तियों के दूसरे भाग में इस पर अधिक)। यदि कोई विधि जटिल है, और आपने पहले से ही किसी अन्य विषय में विस्तार से वर्णन किया है, तो बस एक लिंक दें।

यदि आपको जो करने की आवश्यकता है वह पहले से ही किसी अन्य विषय में कहीं वर्णित है:
बस इस विषय का लिंक दीजिए।

यदि कोई विशिष्ट निर्देश नहीं है, तो समस्या को हल करने के लिए क्या किया जा सकता है:
कोई भी अतिरिक्त जानकारी प्रदान करें जो उपयोगकर्ता को यह पता लगाने में मदद कर सके कि समस्या का कारण क्या हो सकता है।

निष्कर्ष (आउटरो)

निष्कर्ष में, आप कार्य से संबंधित अतिरिक्त जानकारी या समस्या के संभावित समाधान प्रदान कर सकते हैं। आप टिप्स के भाग दो में आउटरो के उपयोग के बारे में अधिक पढ़ सकते हैं।

ग्राफिक्स का उपयोग करना (स्क्रीनशॉट, चार्ट, आरेख, आदि)

स्क्रीनशॉट और आरेख उपयोगकर्ताओं को यह समझने में मदद कर सकते हैं कि विषय में क्या लिखा गया है।

ग्राफिक्स का उपयोग कब करें:

प्रत्येक चरण के तहत, आपको स्क्रीनशॉट डालने की आवश्यकता नहीं है - उपयोगकर्ता को बस यह नहीं पता होता है कि कहाँ देखना है, लगातार स्क्रीन और स्क्रीनशॉट की तुलना करना है।

स्क्रीनशॉट तब डाला जाना चाहिए जब वे निर्देशों में जो लिखा गया है उसे समझने में काफी मदद करें।

उदाहरण के लिए:

• जब आपको एक बटन या आइकन दिखाने की आवश्यकता होती है, जिसमें गुआ का कोई नाम नहीं है, या तुरंत आंख पर प्रहार नहीं करता है, या स्क्रीन पर कई समान हैं;
• जब आपको कार्य के लिए संदर्भ प्रदान करने की आवश्यकता होती है या अंत में यह कैसा और क्या दिखाई देगा, इसका स्पष्ट दृश्य विवरण;
• यदि स्क्रीनशॉट आपको कुछ ऐसा समझने या समझाने की अनुमति देता है जिसके लिए शब्दों में बहुत लंबी और जटिल व्याख्या की आवश्यकता होगी।

शेड्यूल कहां और कैसे लगाएं:

नीचे कुछ सिफारिशें दी गई हैं कि पेज पर ग्राफिक्स कहां और कैसे लगाएं।

1) यदि स्क्रीनशॉट वैचारिक जानकारी या कार्य के परिणाम को दर्शाता है, तो आप इसे इंट्रो के बाद या बाद में सम्मिलित कर सकते हैं।

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



2) यदि स्क्रीनशॉट निर्देशों में एक विशिष्ट चरण को संदर्भित करता है, तो इस चरण के बाद या इसके अंदर डालें:



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



स्पष्ट चीजों को चित्रित करने के लिए ग्राफिक्स का उपयोग न करें।

विशेष रूप से, वर्णन करने के लिए स्क्रीनशॉट का उपयोग न करें:

• मेन्यू
• आइकन, बटन और टैब जिनमें एक नाम है
• बाकी सब कुछ जो आसानी से और आसानी से शब्दों में वर्णित किया जा सकता है।

अंग्रेजी में प्रलेखन लिखने वालों के लिए अतिरिक्त सुझाव:


1) शीर्षकों को कैसे भुनाना है:

पूंजीकरण पूंजीकरण की तीन शैलियां उपलब्ध हैं: वाक्य शैली, शीर्षक शैली और सभी टोपियां।

• वाक्य-शैली पूंजीकरण: यह पंक्ति वाक्य-शैली के पूंजीकरण का उदाहरण प्रस्तुत करती है।
• शीर्षक-शैली पूंजीकरण: यह पंक्ति शीर्षक-शैली पूंजीकरण का एक उदाहरण प्रदान करती है।
• सभी कैप: इस लाइन में सभी कैप का एक प्रस्ताव है।

जोर देने के लिए सभी कैप का उपयोग न करें।

कैपिटलाइज़ेशन (वाक्य शैली): जब आप वाक्य-शैली के कैपिटलाइज़ेशन का उपयोग करते हैं, तो पहले शब्द के पहले अक्षर और साथ ही किसी भी उचित संज्ञा और उचित विशेषण के पहले अक्षर को कैपिटलाइज़ करें।
कैपिटलाइज़ेशन (शीर्षक शैली): पुस्तक के शीर्षक, भाग शीर्षक, अध्याय शीर्षक और अनुभाग शीर्षक (पाठ प्रमुख) के लिए शीर्षक-शैली कैपिटलाइज़ेशन का उपयोग करें।

जब आप शीर्षक-शैली कैपिटलाइज़ेशन का उपयोग करते हैं तो इन नियमों का पालन करें। हर शब्द को कैपिटलाइज़ करें:

• लेख (ए, ए), जब तक कि कोई लेख पहला शब्द नहीं है या एक बृहदान्त्र का अनुसरण नहीं करता है
• समन्वयन संयोजनों (और, लेकिन, या, न, के लिए, अभी तक, और इसी तरह)
• शिशुओं में शब्द (अपने प्रिंटर को कैसे कनेक्ट करें)
• वाणी के भाग की परवाह किए बिना शब्द
• ऐसे शब्द जो हमेशा iPhone और iPad जैसे निचले अक्षर से शुरू होते हैं।
• जब शब्द एक क्रिया वाक्यांश का हिस्सा हो, तब चार अक्षरों या उससे कम (की, से, के लिए, पर, में, बंद, पर, बाहर, पर, ऊपर, और) के प्रस्ताव। उदाहरण के लिए:
  
  ComputerLog को शुरू करें
  ServerGet में
  समानताएं डेस्कटॉप के साथ शुरू हुई

कैपिटल:

• वाक् के भाग की परवाह किए बिना पहला और अंतिम शब्द:
लिनक्स उपयोगकर्ताओं के लिए

क्या समानताएं उपकरण के लिए हैं

• एक हाइफ़न में दूसरा शब्द यौगिक:

सही: उच्च-स्तरीय ईवेंट, 32-बिट एड्रेसिंग
गलत: उच्च-स्तरीय ईवेंट, 32-बिट एड्रेसिंग
अपवाद: अंतर्निहित, प्लग-इन

• शब्द हैं, इफ, इज़, इट, थान, दैट, एंड दिस

2) "क्लिक" शब्द का उपयोग कैसे करें:

क्लिक का उपयोग करें क्लिक करें ऑनस्क्रीन एक वस्तु पर पॉइंटर की स्थिति का वर्णन करने के लिए और माउस बटन को संक्षेप में दबाने और जारी करने के लिए। क्लिक का उपयोग न करें। क्योंकि अधिकांश उपयोगकर्ता जानते हैं कि क्लिकिंग क्या है, आपको इसे केवल शुरुआत वाले उपयोगकर्ताओं के लिए डिज़ाइन किए गए दस्तावेज़ीकरण में परिभाषित करने की आवश्यकता है, जैसे कि ट्यूटोरियल।
सही: मैक पर क्लिक करें यदि आप मैक ओएस एक्स के साथ यूएसबी डिवाइस का उपयोग करना चाहते हैं।

गलत: मैक को इंगित करें और यदि आप मैक ओएस एक्स में यूएसबी डिवाइस का उपयोग करना चाहते हैं तो इसे क्लिक करें।
उपयोग न करें पर क्लिक करें; क्लिक का उपयोग करें।

3) ईमेल या ई-मेल?

ईमेल का उपयोग करें। ई-मेल का उपयोग न करें।

4) यदि या क्या?

यदि किसी शर्त को व्यक्त करने के लिए उपयोग करें। उपयोग करें कि क्या विकल्प व्यक्त करें।
सही: जांचें कि क्या समानताएं उपकरण स्थापित किए गए हैं।
गलत: जांचें कि क्या समानताएं उपकरण स्थापित किए गए हैं।
सही: Mac पर क्लिक करें यदि आप Mac OS X के साथ USB डिवाइस का उपयोग करना चाहते हैं।

5) उत्पाद नाम का उपयोग कैसे करें:

उत्पाद की पैकेजिंग पर पूंजीकरण शैली का पालन करें। पाठ के एक खंड के भीतर इसकी पहली घटना के लिए पूर्ण उत्पाद नाम का उपयोग करें (उदाहरण के लिए, एक अध्याय)। इसके बाद, जब लागू उत्पाद के नाम का एक छोटा संस्करण का उपयोग करें।

उदाहरण के लिए: मैक के लिए समानताएं डेस्कटॉप 14: पाठ के एक खंड के भीतर पहली घटना पर, मैक के लिए समानताएं डेस्कटॉप 14 का उपयोग करें।

बाद की घटनाओं पर, समानताएं डेस्कटॉप का उपयोग करें।

निष्कर्ष

मैनुअल के इन 3 भागों में, हमने उन सुझावों को एक साथ रखने, संक्षेपित करने और संरचना करने की कोशिश की, जो आपके प्रलेखन को आसान और अधिक समझने में मदद करेंगे।

हम इस बात पर जोर नहीं देते हैं कि लेखन इस तरह से आवश्यक है - प्रलेखन और तकनीकों के कई दृष्टिकोण हैं। सेटिंग को देखें और जो आपके अनुरूप है उसका उपयोग करें।

आपका ध्यान और रुचि के लिए बहुत बहुत धन्यवाद!