समस्या तय करें

“ऐसी style guide जिसका लोग वास्तव में उपयोग करें” को तकनीकी दस्तावेज़ीकरण के लिए व्यावहारिक, जाँच योग्य और टिकाऊ तरीके से समझाया गया है। शुरुआत में वास्तविक उपयोगकर्ता समस्या को टीम की आंतरिक पसंद से अलग करें और ऐसी शर्तें लिखें जिन्हें पाठक बिना आंतरिक संदर्भ के लागू कर सके। “ऐसी style guide जिसका लोग वास्तव में उपयोग करें” में इस उद्देश्य को ऐसे ठोस निर्णय में बदलें जिसे दूसरा लेखक जाँच और दोहरा सके।

उपयोगी मॉडल चुनें

“ऐसी style guide जिसका लोग वास्तव में उपयोग करें” को स्पष्ट, जाँच योग्य निर्णयों में बाँटें। हर भाग में तथ्य, सिफारिश और अपवाद अलग हों ताकि तकनीकी और संपादकीय review केंद्रित रहे। इस विषय में सबसे संभावित exception भी लिखें; स्पष्ट दिखने वाले नियम अक्सर वहीं टूटते हैं।

workflow में जोड़ें

तरीका सामान्य authoring, review, build और publication workflow में फिट होना चाहिए। केवल विशेष cleanup के समय चलने वाली प्रक्रिया टिकती नहीं है। workflow में साफ दिखना चाहिए कि तथ्य कौन verify करता है, text कौन edit करता है और review कब पूरा माना जाता है। इस लेख में यही कसौटी विशेष रूप से “ऐसी style guide जिसका लोग वास्तव में उपयोग करें” पर लागू होती है।

परिणाम जाँचें

प्रकाशन से पहले terminology, prerequisites, examples और वास्तविक product behavior से मेल की जाँच करें। सहज भाषा verified fact की जगह नहीं लेती। recommendation को वास्तविक task या observable product state पर जाँचें, केवल सहज भाषा पर नहीं। इस लेख में यही कसौटी विशेष रूप से “ऐसी style guide जिसका लोग वास्तव में उपयोग करें” पर लागू होती है।

इसे बनाए रखने योग्य रखें

समाधान इतना छोटा रखें कि टीम उसे बनाए रख सके। coordination का खर्च लाभ से अधिक हो तो scope घटाएँ और केवल उपयोगी नियम रखें। process का वही हिस्सा रखें जो reader को सुरक्षित या सफल बनाता है; बाकी को हटाने योग्य होना चाहिए। इस लेख में यही कसौटी विशेष रूप से “ऐसी style guide जिसका लोग वास्तव में उपयोग करें” पर लागू होती है।

व्यावहारिक उदाहरण

“ऐसी style guide जिसका लोग वास्तव में उपयोग करें” को किसी वास्तविक page पर लागू करें। ऐसा content चुनें जिसमें headings, table, note, example, दोहराया गया term और कम-से-कम एक reader action हो। पहले author की तरह और फिर उस reader की तरह review करें जो internal vocabulary नहीं जानता।

Observable defects लिखें:

  • कौन-सी structure ऐसा meaning देती है जो plain text में नहीं है;
  • कौन-सा term spelling या meaning बदलता है;
  • कौन-सी instruction unstated context पर निर्भर है;
  • कौन-सा rule review में consistently check करना कठिन है।

Standard तब उपयोगी है जब दो editors उसी content पर लगभग समान निर्णय ले सकें। यदि rule सही लगता है पर representative page पर दिखाया नहीं जा सकता, तो उसे स्पष्ट करें, example जोड़ें या scope छोटा करें।

त्वरित संपादकीय जाँच

  • समस्या तय करें. “ऐसी style guide जिसका लोग वास्तव में उपयोग करें” को तकनीकी दस्तावेज़ीकरण के लिए व्यावहारिक, जाँच योग्य और टिकाऊ तरीके से समझाया गया है। शुरुआत में वास्तविक उपयोगकर्ता समस्या को टीम की आंतरिक पसंद से अलग करें और ऐसी शर्तें लिखें जिन्हें पाठ…
  • उपयोगी मॉडल चुनें. “ऐसी style guide जिसका लोग वास्तव में उपयोग करें” को स्पष्ट, जाँच योग्य निर्णयों में बाँटें। हर भाग में तथ्य, सिफारिश और अपवाद अलग हों ताकि तकनीकी और संपादकीय review केंद्रित रहे। इस विषय में सबसे संभावित exception भी लिखें; स्पष्ट दिखने वा…
  • workflow में जोड़ें. तरीका सामान्य authoring, review, build और publication workflow में फिट होना चाहिए। केवल विशेष cleanup के समय चलने वाली प्रक्रिया टिकती नहीं है। workflow में साफ दिखना चाहिए कि तथ्य कौन verify करता है, text कौन edit करता है और review कब पूरा…
  • परिणाम जाँचें. प्रकाशन से पहले terminology, prerequisites, examples और वास्तविक product behavior से मेल की जाँच करें। सहज भाषा verified fact की जगह नहीं लेती। recommendation को वास्तविक task या observable product state पर जाँचें, केवल सहज भाषा पर नहीं। इस…

संबंधित सामग्री