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

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

पिछले लेख में, हमने उल्लिखित किया था कि हमारे उत्पादों के दस्तावेजीकरण और स्थानीयकरण की प्रक्रिया कैसे होती है।

इस बार, कटौती के तहत, हमारे तकनीकी लेखक आंद्रेई स्टारोवितोव का मैनुअल है, जो उपयोगकर्ताओं के लिए आपके दस्तावेज़ को आसान और अधिक समझने में मदद करेगा (वर्णित तकनीकों का उपयोग ऐप्पल, माइक्रोसॉफ्ट और अन्य कंपनियों द्वारा अपने उत्पादों के दस्तावेज के लिए किया जाता है)।

जैसा कि आप जानते हैं, अच्छा प्रलेखन एक लक्जरी नहीं है, बल्कि कंपनी की बिक्री बढ़ाने का एक साधन है। यदि आप शुरू करने जा रहे हैं या पहले से ही किसी प्रकार का कार्यक्रम विकसित कर रहे हैं, तो इसके साथ विश्व बाजार में प्रवेश करने के लिए, आपको एक उपयोगकर्ता पुस्तिका (उर्फ यूजर गाइड) या कम से कम एक दस्तावेज की आवश्यकता होगी जो ग्राहकों को आपके उत्पाद (तथाकथित) के साथ काम करना शुरू करने के बारे में बताए। के साथ शुरू हो रही है)।

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

तो प्रलेखन लिखते समय आपको क्या देखना चाहिए?

प्रलेखन में विषयों के प्रकार

विषय लिखते समय, पहले आपको यह निर्धारित करने की आवश्यकता है कि यह किस प्रकार का विषय होगा :)

इससे इस पर निर्भर करेगा कि इसमें क्या और कैसे लिखना है।

4 मुख्य विषय हैं :

• विषय जो किसी विशिष्ट कार्य या कई संबंधित कार्यों को हल करने का वर्णन करते हैं (अंग्रेजी में इस प्रकार के विषय को कार्य पृष्ठ कहा जाता है ) ।

उदाहरण के लिए, "समानताएं डेस्कटॉप स्थापित करें" या "शट डाउन या विंडोज को रोकें।" इनमें से प्रत्येक विषय एक या एक से अधिक चरणों की एक श्रृंखला का वर्णन करता है जो एक उपयोगकर्ता को एक विशिष्ट लक्ष्य प्राप्त करने के लिए लेना चाहिए। उपयोगकर्ता पुस्तिका में मुख्य रूप से ऐसे विषय होते हैं।

आमतौर पर यूजर्स पढ़ना पसंद नहीं करते हैं, खासकर जब बहुत सारा टेक्स्ट हो। इसलिए, आपको ऐसे विषयों को यथासंभव छोटा करने का प्रयास करना चाहिए। आदर्श रूप से, यदि जानकारी निम्नलिखित रूप में प्रस्तुत की गई है: "आप कुछ कर सकते हैं, बस यहां और यहां क्लिक करें" (कार्य विषयों पर लेख के अगले भाग में अधिक विस्तार से चर्चा की जाएगी)।

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

• वैचारिक विषय (अंग्रेजी में - अवधारणा पृष्ठ )। इन विषयों में किसी भी समस्या को हल करने के लिए कोई निर्देश नहीं हैं। उनमें ऐसी जानकारी होती है जो चीजों की अधिक समझ में योगदान देती है। उदाहरण के लिए, वैचारिक विषयों का उपयोग किया जाता है:

- उपयोगकर्ताओं को बिल्कुल समझाएं कि कोई भी प्रक्रिया कैसे काम करती है;
- बताएं कि एप्लिकेशन सेटिंग्स में क्या किया जा सकता है;
- उत्पाद के नए संस्करण में अतिरिक्त सुविधाओं का वर्णन करें;
- अतिरिक्त जानकारी प्रदान करें जो उपयोगकर्ता को किसी समस्या को बेहतर ढंग से समझने या हल करने में मदद करेगी।

कृपया ध्यान दें कि अतिरिक्त जानकारी (यदि इसके बारे में बहुत कुछ है) वैचारिक विषय में सटीक रूप से प्रदान की जानी चाहिए ताकि कार्य विषय को अधिभार न डालें।

• मदद विषय (अंग्रेजी में - संदर्भ पृष्ठों ) - जानकारी है कि उपयोगकर्ता समय-समय पर यह पता लगाने के लिए संदर्भित कर सकते हैं कि किसी विशेष शब्द का अर्थ क्या है, एक फ़ंक्शन कैसे काम करता है, आदि। इस तरह के विषयों का एक अच्छा उदाहरण मार्गदर्शक (उर्फ ग्लोसरी) के अंत में शब्दकोष है। विभिन्न इंटरफ़ेस तत्वों के उद्देश्य को समझाने के लिए संदर्भ विषय विशेष रूप से उपयोगी हैं।

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

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

सभी प्रकार के प्रलेखन के लिए बुनियादी निर्देश

एक गाइड बनाते समय:

1) उपयोगकर्ता पर ध्यान लगाओ

• इसकी विशेषताओं या इंटरफ़ेस तत्वों के आधार पर उत्पाद विवरण को संरचित करने के बजाय, उन कार्यों पर ध्यान केंद्रित करने का प्रयास करें जिन्हें उपयोगकर्ता को हल करने की कोशिश करने की सबसे अधिक संभावना है।

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

क) "सुरक्षा सेटिंग्स", जो विस्तार से वर्णन करता है कि डेटा की सुरक्षा के लिए क्या किया जा सकता है।

बी) विशिष्ट कार्यों का वर्णन करने वाले कई विषय बनाएं:

- "एंटीवायरस सॉफ्टवेयर के साथ अपने डेटा को सुरक्षित रखें"

- "अपनी वर्चुअल मशीन का बैकअप लें" ("बैक अप योर वर्चुअल मशीन")

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

• उपयोगकर्ता और उसके तकनीकी साक्षरता के स्तर के कार्यों पर ध्यान दें।

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

हालाँकि हबर के अधिकांश पाठकों के लिए यह क्या है, यह "शॉर्टकट कॉन्फ़िगर करें" के लिए स्पष्ट होगा, लेकिन यह सवाल पहले से ही है कि इस समय आधिकारिक शब्दावली में ऐसा शब्द कितना उपयुक्त है :)

• यदि यह स्पष्ट नहीं हो सकता है, तो बताएं कि उपयोगकर्ता को किसी विशेष कार्य को करने की आवश्यकता क्यों हो सकती है।

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



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

उदाहरण के लिए, "पारदर्शी" के बजाय "पारदर्शी"। यदि आप अंग्रेजी भाषा से एक उदाहरण देते हैं, तो "उपयोग" के बजाय "उपयोग" करें।

2) अनावश्यक शब्दों के बिना सभी आवश्यक जानकारी देने का प्रयास करें

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

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

उपयोगकर्ताओं को उनकी ज़रूरत की सभी जानकारी खोजने में मदद करने के लिए और साथ ही साथ प्रत्येक अनुभाग का संक्षेप में वर्णन करें:

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

3) पृष्ठों पर एक ही जानकारी न दोहराएं

प्रत्येक विषय में जानकारी को दोहराने के बजाय जो पहले से ही किसी अन्य विषय में वर्णित है, यह संदर्भित करना बेहतर है कि इस तरह के विषय में अधिक विस्तृत विवरण पाया जा सकता है, या बस इसे हाइपरलिंक दें।

4) उपयोगकर्ता का ध्यान सही तरीके से आकर्षित करें

जब विवरण को उपयोगकर्ता का ध्यान आकर्षित करने की आवश्यकता होती है, तो निम्नलिखित परिचयात्मक शब्दों का उपयोग किया जाता है - "ध्यान दें!" (अंग्रेजी में - चेतावनी!), "महत्वपूर्ण:" (अंग्रेजी में - महत्वपूर्ण :) और "नोट:" (अंग्रेजी में - नोट :)।

इन शब्दों में से प्रत्येक का अर्थ है "महत्व" का अपना स्तर।

उपयोगकर्ता को व्यर्थ में तनाव न देने के लिए, प्रत्येक शब्द का सही उपयोग करें:

• ध्यान का प्रयोग करें ! (चेतावनी; अंग्रेजी में) एक खतरनाक स्थिति को इंगित करने के लिए, जिसे अगर टाला नहीं जाता है, तो डेटा हानि, घटक क्षति, या अन्य नुकसान हो सकता है।
• "महत्वपूर्ण:" का उपयोग करें (अंग्रेजी में - महत्वपूर्ण :) एक महत्वपूर्ण और संभावित समस्याग्रस्त स्थिति को इंगित करने के लिए, जो, हालांकि, शारीरिक क्षति, क्षति या डेटा हानि का कारण नहीं बन सकता है।
• इस विषय से संबंधित कोई अतिरिक्त जानकारी प्रदान करने के लिए "नोट:" (नोट :) का उपयोग करें। यद्यपि इस तरह के सम्मिलन से उपयोगकर्ता वर्तमान कार्य से अलग हो जाते हैं, यह उपयोगी हो सकता है।

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

वर्चुअल मशीन कॉन्फ़िगरेशन खोलने के लिए, क्रिया> कॉन्फ़िगर करें पर क्लिक करें।
नोट: वर्चुअल मशीन को बंद कर दिया जाना चाहिए।

नोट का उपयोग करें "नोट:" संयम से - यदि आप इसे बहुत बार सम्मिलित करते हैं, तो यह पाठ को रोक देता है, और यह उस पर ध्यान देना बंद कर देता है।

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

एक उदाहरण:



जारी रखने के लिए ...

(लेख के अगले भाग में हम और अधिक विस्तार से चर्चा करेंगे जो एक विशिष्ट समस्या को हल करने के तरीके का वर्णन करते हैं)