प्रलेखन पर काम करने के लिए 50 प्रश्न

कोई फर्क नहीं पड़ता कि यूएक्स डिजाइनर कितना मुश्किल कोशिश करता है, सड़क से एक व्यक्ति बिना संकेत के अंतरिक्ष यान नियंत्रण इंटरफ़ेस का पता लगाने में सक्षम नहीं होगा। और गली से भी नहीं। सिर्फ इसलिए कि रॉकेट बड़ा है और बहुत सारी सेटिंग्स हैं।

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

हमारे पास छह उत्पाद हैं, जिसके लिए कंपनी की बहुत नींव से प्रलेखन डेवलपर्स द्वारा लिखा गया था। आधे साल से हम पुराने लेखों को फिर से लिख रहे हैं और नए लेख लिख रहे हैं । कटौती के तहत - 50 प्रश्न जो हमें यह अच्छी तरह से करने में मदद करते हैं। लेकिन एक शुरुआत के लिए, थोड़ा परिचयात्मक।

दस्तावेज़ीकरण क्यों महत्वपूर्ण है, और इसे किसे करना चाहिए

एक अच्छा डॉक बनाना कठिन है। कहीं न कहीं विश्लेषकों, लेखकों और संपादकों का एक बड़ा विभाग इस पर काम कर रहा है, और कहीं-कहीं डेवलपर्स डॉक (किया - वर्णित) को लिख रहे हैं।

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

यदि आपके पास एक छोटा तकनीकी लेखक है, तो अन्य विभागों के कर्मचारियों की भर्ती करें। यदि वे रुचि नहीं रखते हैं, तो नीचे दी गई सूची से तर्क दें। पहला समर्थन, दूसरा और तीसरा विपणन और उत्पाद विपणन। तो प्रलेखन क्यों महत्वपूर्ण है?

1. समर्थन कारक । पहला और सबसे स्पष्ट कारण। यदि दस्तावेज़ अच्छा है, तो अधिकांश ग्राहक समर्थन से संपर्क किए बिना समस्या का समाधान करेंगे। शेष समर्थन निर्देशों का लिंक फेंक देगा या जल्दी से स्वयं इसके माध्यम से जाएगा। चैट बॉट बनाने के लिए पूर्ण प्रलेखन का उपयोग किया जा सकता है। यह सब ग्राहकों के लिए प्रतिक्रिया समय को कम करता है, उनकी संतुष्टि को बढ़ाता है, और समर्थन लागत को भी कम करता है।
2. चयन कारक । प्रलेखन मूल्य, सुविधा, कार्यक्षमता के साथ ग्राहक की पसंद को प्रभावित करता है। इसकी पुष्टि हमारे शोध और ISPmanager और DCImanager उपयोगकर्ताओं की प्रतिक्रिया से होती है । इस नस में, गोदी समर्थन की आवश्यकता के रूप में बंद हो जाता है, लेकिन प्रतिस्पर्धी लाभ, विपणन का हिस्सा बन जाता है।
3. वफादारी का कारक । यदि क्लाइंट शुरुआत में या प्रक्रिया में डॉक को समझने के बिना छोड़ दिया, तो यह एक समस्या है। खराब लेखों के कारण किसी ग्राहक को आकर्षित करना खोना बहुत महंगा है।

अच्छा प्रलेखन कैसे करें

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

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

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

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

डॉक पर काम करने के लिए 50 सवाल

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

लक्ष्यों

1. मैं किसके लिए एक लेख लिख रहा हूं? भविष्य का पाठक कौन है: उपयोगकर्ता, व्यवस्थापक, डेवलपर?
2. यह किस कार्य का सामना करता है (नौकरियों के लिए किया जाता है)? क्या व्यक्ति का वर्णन है?
3. इस उपयोगकर्ता के प्रशिक्षण का स्तर क्या है? वह पहले से ही क्या जानता है? उसके लिए क्या स्पष्ट नहीं है?
4. नौसिखिए उपयोगकर्ता को यह कैसे समझाया जा सकता है और बुनियादी चीजों की उन्नत व्याख्या से नाराज नहीं होना चाहिए?
5. उपयोगकर्ता को और क्या समझाया जाना चाहिए ताकि वह लेख की मुख्य सामग्री को समझ सके?
6. इस लेख का प्रलेखन किस भाग के लिए उपयुक्त है?
7. क्या इस लेख या इसके भाग को अन्य वर्गों में दोहराया जाना चाहिए?
8. मुझे किन लेखों से लिंक करना चाहिए?
9. शायद यह लेख एक वीडियो निर्देश के साथ होना चाहिए?

जानकारी के स्रोत

10. क्या वर्तमान उपयोगकर्ताओं को लेख के विषय के साथ समस्या है?
11. अब समर्थन कैसे समझाता है कि क्या करने की ज़रूरत है?
12. क्या विपणन विभाग ने इस विषय पर ब्लॉग लेख और समाचार लिखे हैं? क्या वे अपने शब्दांकन, संरचना आदि को "जासूसी" कर सकते हैं?
13. क्या साइट पर इस विषय पर कोई अनुभाग हैं?
14. स्क्रिप्ट में UX और उत्पाद प्रबंधक शामिल थे? ऐसा क्यों किया?
15. यह प्रश्न प्रतियोगियों द्वारा कैसे वर्णित किया गया है?
16. किन क्षेत्रों में आप अभी भी सर्वोत्तम प्रथाओं को देख सकते हैं?

सामग्री की जाँच

17. क्या आपने लेख के लक्ष्य को प्राप्त किया?
18. क्या अधिक उन्नत उपयोगकर्ता के लिए सब कुछ स्पष्ट होगा?
19. क्या नौसिखिए उपयोगकर्ता के लिए सब कुछ स्पष्ट होगा?
20. क्या सब कुछ तार्किक और सुसंगत है? कोई छलांग और रसातल?
21. क्या क्रियाओं का क्रम सही है? क्या उपयोगकर्ता केवल इस निर्देश का पालन करके लक्ष्य प्राप्त कर पाएंगे?
22. क्या हमने सभी मामलों / उपयोगकर्ता पथों को ध्यान में रखा है?
23. क्या लेख चयनित अनुभाग में फिट बैठता है?

लेआउट की जाँच

24. क्या पाठ की कोई अपठनीय चादरें हैं? क्या सर्किट को बदलना संभव है?
25. क्या लंबे पैराग्राफ हैं?
26. क्या बहुत कम पैराग्राफ हैं?
27. क्या बहुत लंबी सूची है?
28. क्या धारणा के लिए बहुत अधिक जटिल हैं (जिनमें दो या तीन से अधिक स्तर हैं)?
29. क्या पर्याप्त छवियां हैं?
30. बहुत सारे चित्र नहीं हैं? क्या हम बहुत स्पष्ट कदम बता रहे हैं?
31. यदि योजनाएं हैं, तो क्या वे समझ में आते हैं?
32. टेबल्स धारणा के लिए मुश्किल नहीं हैं?
33. क्या पेज कुल मिलाकर अच्छा दिखता है?

साहित्य संपादन

34. क्या सब कुछ गाइड के अनुसार बनाया गया है?
35. क्या बाकी दस्तावेज़ों की शैली सुसंगत है?
36. कोई भी सुझाव जो सरल बनाया जा सकता है?
37. क्या ऐसी जटिल शर्तें हैं जिन्हें स्पष्टीकरण की आवश्यकता है?
38. क्या एक लिपिकवाद है?
39. क्या एक पुनरावृत्ति है?
40. क्या आपके सुनने से कुछ नहीं होता है?

अंतिम प्रमाण

41. क्या टाइपोस, वर्तनी या विराम चिह्न त्रुटियां हैं?
42. क्या हाइफ़न, पैराग्राफ़ और सेक्शन ठीक हैं?
43. क्या सभी चित्र हस्ताक्षरित हैं?
44. क्या इंटरफ़ेस तत्वों को सही नाम दिया गया है?
45. क्या हर जगह लिंक हैं? क्या वे काम करते हैं और वे कहाँ जाते हैं?

प्रकाशन के तुरंत बाद

46. ​​क्या लेख में ऐसे अनुभाग हैं जो अन्य लेखों में "खींचे" गए हैं? क्या उन्हें मैक्रोज़ से सजाया गया है ताकि एक लेख में परिवर्तन स्वचालित रूप से दूसरों पर लागू हो?
47. क्या इस लेख को अन्य वर्गों से संदर्भित किया जाना चाहिए? यदि हां, तो किसमें?
48. उत्पाद में इस लेख के लिए एक त्वरित लिंक जोड़ने की आवश्यकता है?
49. क्या मुझे समर्थन, विपणन या अन्य विभागों के लिए लिंक भेजना है?
50. क्या मुझे अनुवाद के लिए एक लेख प्रस्तुत करना होगा?

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