कामों नहीं, निर्णयों पर केंद्रित दृष्टिकोण

• निर्णयों पर ध्यान केंद्रित करना

  • Every Page Is Page One का एक उद्धरण तकनीकी दस्तावेज़ लेखन के दृष्टिकोण में बड़ा बदलाव लाता है
  • तकनीकी संचार में आमतौर पर task support की बात होती है, लेकिन कई मामलों में लोगों को काम पूरा करने के लिए मशीन कैसे चलती है यह नहीं, बल्कि decision-support information की ज़रूरत होती है
  • केवल प्रक्रियाओं का दस्तावेज़ीकरण करना पर्याप्त नहीं है
  • उपयोगकर्ता को यह बताना चाहिए कि उन्हें कौन से निर्णय लेने हैं और उनके परिणाम क्या होंगे, तथा जहाँ तक संभव हो उन्हें निर्णय लेने में मदद करने वाले resources और reference materials की ओर ले जाना चाहिए

GN⁺ की संक्षिप्त प्रस्तुति

• यह लेख तकनीकी दस्तावेज़ लेखन में decision support के महत्व पर ज़ोर देता है
• केवल प्रक्रियात्मक विवरण से आगे बढ़कर उपयोगकर्ताओं को बेहतर निर्णय लेने में मदद करना ज़रूरी है
• तकनीकी दस्तावेज़ लेखकों के लिए उपयोगकर्ताओं को आवश्यक context और information देना महत्वपूर्ण है
• समान कार्यक्षमता वाले उद्योग के प्रोजेक्ट्स में Confluence और Notion की सिफारिश की जाती है

[GN⁺]

Hacker News टिप्पणियाँ

• जर्मन bureaucracy के बारे में लिखते हुए, मैं इस approach से पूरी तरह सहमत हूँ
  मेरी ज़्यादातर guides “यह क्या है, इसे किसे करना चाहिए, और क्यों करना चाहिए” से शुरू होती हैं। अगर आप यह सुनिश्चित नहीं करते कि लोग सही वजहों से सही काम कर रहे हैं, तो वे बहुत दूर तक गलत दिशा में जा सकते हैं
  ज़्यादातर सरकारी websites यह सब नहीं समझातीं, और सिर्फ वही माँगती हैं जो उनके हिस्से की प्रक्रिया पूरी करने के लिए ज़रूरी है। वे इसे किसी बड़े decision का हिस्सा नहीं मानतीं, और यह मानकर चलती हैं कि user पहले से जानता है कि वह क्या कर रहा है

  • आखिरी paragraph के संदर्भ में, UK gov website यह काम बहुत अच्छे से करती है। प्रक्रिया समझाने वाला एक landing page होता है, और warnings व सावधानियों के बाद ही आप असल form भर सकते हैं
    driving licence renew करने के Google result https://www.gov.uk/renew-driving-licence पर “Start Now” दबाकर देखें, तो मतलब समझ आ जाएगा
    “power user” के तौर पर यह कभी-कभी रुकावट जैसा लगता है, लेकिन समझ आता है कि सभी को ध्यान में रखना पड़ता है
  • यह comment देखकर लगता है कि आपको Every Page Is Page One पसंद आएगी। मुख्य बात यह है कि लोग documentation site के किसी भी page पर आ सकते हैं, इसलिए हर page को जल्दी context देना चाहिए और user को आसानी से यह तय करने देना चाहिए कि वह सही रास्ते पर है या नहीं
    किताब का title भी यहीं से आया है। site का कोई भी page user के लिए पहला page हो सकता है
  • काश यह approach और ज़्यादा technical documentation में होती। मैं अक्सर यह जानना चाहता हूँ कि कोई चीज़ किसी खास तरीके से क्यों की जाती है, इसलिए side topics में भटक जाता हूँ और गति धीमी हो जाती है

• यह LLM इस्तेमाल करने के तरीके से अच्छी तरह मेल खाता है। मैं हमेशा options माँगता हूँ, फिर खुद तय करता हूँ कि उनमें से क्या सबसे ज़्यादा समझ में आता है
  मूल रूप से मैं इसे एक अजीब जादुई document की तरह इस्तेमाल कर रहा हूँ, जो decision-making के हर पल पर संभावित options को अधूरे लेकिन उपयोगी तरीके से उगल देता है

  • Leonardo जैसे मशहूर artist के अधीन काम करने वाले apprentices को याद करें। master outline और sketch बनाता था, और students निगरानी में खाली हिस्से भरते थे। कभी-कभी master students के ideas चुरा भी लेता था
  • क्या आप इस तरीके का कोई example दे सकते हैं?

• बहुत अच्छा। छोटा, सीधा और insightful। मेरी सोच big picture देखने वाली है, इसलिए किसी चीज़ का सिर्फ तरीका ही नहीं, बल्कि वह क्यों है और बड़े context से कैसे जुड़ती है, यह भी मेरे लिए महत्वपूर्ण है
  मैं developers को encourage करता हूँ कि वे Jira stories और tasks के Description field का सक्रिय रूप से इस्तेमाल करें, ताकि हम यह काम क्यों कर रहे हैं और यह big picture से कैसे जुड़ता है, इसका overview शामिल हो। कुछ लोगों को यह पसंद नहीं लगता, लेकिन कुछ को काफी पसंद आता है
  मुझे project का big picture देना अच्छा लगता है, और developers उस big picture को समझकर ज़्यादा independent तरीके से काम कर पाते हैं, इससे वे संतुष्ट होते हैं

• यह मापना कि documentation लोगों को अच्छे decisions लेने में मदद करती है या नहीं, इस बात को मापने से कहीं ज़्यादा कठिन लगता है कि वह उन्हें कोई task सफलतापूर्वक पूरा करने में मदद करती है या नहीं
  task-based और procedural documentation के लिए optimize करने की वजह यह है कि कंपनियाँ documentation team से अपना value prove करने को कहती हैं, ऐसी docs की demand होती है, और कम समय में measure व report करने के कई तरीके उपलब्ध होते हैं
  लेकिन “क्या इस docs के bundle ने किसी को सही चीज़ सही तरीके से बनाने में मदद की?” यह सवाल तो organizations के लिए अपने product के बारे में जवाब देना भी कठिन होता है; documentation effect के रूप में abstract करने पर यह और भी धुंधला हो जाता है
  इसका मतलब यह नहीं कि decision में मदद करने वाली documentation लिखी नहीं जा सकती, बल्कि यह कि यह numbers से prove करना बहुत कठिन है कि आपने ऐसा किया। मैं rank कर सकता हूँ और वजहें भी बता सकता हूँ कि अलग-अलग docs bundles decision लेने की ज़रूरत वाले users को कितनी अच्छी तरह support करते हैं, लेकिन इसे कंपनी की चाही हुई शैली में quantify कैसे करें, यह मुझे ठीक से नहीं पता
  यह भी जानने की उत्सुकता है कि decision support के लिए design किए गए docs bundle की structure task support करने वाली docs से कैसे अलग होगी। बड़े categories शायद concepts, reference, guides ही रहेंगी, लेकिन concept docs कहीं ज़्यादा होंगी और concepts को contextualize करने की जगह भी ज़्यादा होगी। topics के बीच dependencies और cross-references भी बढ़ने की उम्मीद है

  • दिलचस्प है कि पहला विचार “मैं इसे अपनी docs सुधारने में कैसे इस्तेमाल करूँ?” नहीं बल्कि “मैं कैसे prove करूँ कि यह मेरी docs को सुधारता है?” है। लगता है आप काफी tight environment में काम करते हैं
  • जहाँ personal projects की तरह users के लिए जो best लगता है उसे freely किया जा सकता है, वहाँ decision support को documentation strategy का आधार बनाने की संभावना अधिक है
    ईमानदारी से काम करने के नज़रिए से, अगर मेरे project में “decision support” मुझे सबसे अच्छा लगता है, तो शायद मेरी जिम्मेदारी है कि work docs में भी यह strategy ले जाऊँ
    सौभाग्य से short-sighted managers मेरा गला नहीं घोंट रहे, लेकिन अगर workplace में convince करना पड़े तो मैं ऐसा करूँगा। पहले strategy का logic समझाऊँगा। decision support समझ में आता है और persuasive भी है। task docs फिर भी लिखी जाएँगी, लेकिन tasks decision support का सिर्फ subset हैं
    फिर support tickets, chatroom discussions आदि से ऐसे लंबी examples दूँगा जहाँ decision support की कमी problem थी। intellectual honesty के लिए documentation-related support tickets की पूरी list और उनमें decision support से जुड़ा subset साथ दिखाऊँगा। अगर अनुपात नज़रअंदाज़ न करने लायक हो, जैसे 25%, तो “decision support” को और गहराई से देखना चाहिए
    आखिर में stakeholders अपने काम में झेले examples दे सकते हैं। जैसे, “याद है CMS किससे replace करना है यह decide करना कितना मुश्किल था?”

• आम तौर पर मैं इसे heuristic approach कहता हूँ
  मुझे लगता है काम में fuzzy logic जैसा approach चाहिए। हालांकि यह सबसे अच्छा तब काम करता है जब engineer के पास कुछ experience हो
  अगर experience कम है, तो skill अच्छी और smart होने पर भी, बहुत ज़्यादा directive होना पड़ता है

  • Thinking in Bets software engineering को approach करने के तरीके पर मेरे लिए सबसे उपयोगी किताबों में से एक रही। यह code पर किताब नहीं है, बल्कि limited information environment में effective decisions लेने के तरीके पर है
  • मुझे समझ नहीं आया कि काम को fuzzy logic तरीके से approach करने का क्या मतलब है। क्या आप थोड़ा और समझा सकते हैं?

• team context में decisions लेने का अच्छा approach Rich Hickey यहाँ समझाते हैं: https://www.youtube.com/watch?v=c5QF2HjHLSE
  talk का title “Design in Practice” है, लेकिन असल में यह decision-making के बारे में है

• “काम वह सब है जो एक decision से अगले decision तक जाने के लिए करना पड़ता है।” — Venkatesh Rao, Tempo

• मैं भी कुछ ऐसा ही कहता रहा हूँ। टूल्स को सिर्फ high level पर describe न करें; खासकर लोग अक्सर marketing mode में चले जाते हैं। इसके बजाय यह बताना चाहिए कि वह टूल किस समस्या को हल करने के लिए design किया गया था और इस प्रक्रिया में कौन-से trade-offs किए गए।
  इससे टूल और उपलब्ध विकल्पों/मोड्स आदि को context में रखना काफी आसान हो जाता है, और यह जल्दी समझ आता है कि वह अपने लिए सही है या नहीं।

• यह सलाह थोड़ी confusing है। निर्णय किसका है? tool creator का निर्णय, या user का?
  सामान्य तौर पर यह जरूरत से ज्यादा simplification जैसा लगता है। पहले यह समझना ज्यादा उपयोगी है कि आप जो documentation लिख रहे हैं वह learning-oriented, goal-oriented, understanding-oriented या information-oriented में से किस तरह का है [1]
  उदाहरण के लिए, अगर मैं किसी function की API देख रहा हूँ और “decision” information की बाढ़ आ जाए, तो चिढ़ हो सकती है।
  1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

  • documentation को हमेशा user needs को address करना चाहिए। वह बात खत्म नहीं होती। आपने जिस documentation के चार quadrants, यानी Diataxis, का जिक्र किया है, उस पर भी यही लागू होता है।
    मुझे लगता है यह लेख इसलिए resonate करता है क्योंकि यह दो well-known strategies के blind spots दिखाता है। हर कोई user-centered documentation बनाना चाहता है और कई teams Diataxis follow करती हैं, फिर भी लोगों को docs के जरिए काम पूरा करने में मुश्किल होती है।
    “documentation को decisions support करने चाहिए” वाली basic viewpoint से शुरू करना docs को ज्यादा useful बनाने का रास्ता हो सकता है।

• यह जानना जरूरी है कि लोग मेरे system का इस्तेमाल decisions लेने के लिए कैसे करते हैं। मेरी नजर में ऐसा knowledge system को maintain, extend या फिर से build करने के लिए essential है।
  लेकिन लेख इससे ऊँची responsibility propose करता है। यानी user के decision-making process को document करना, और context, options व decision के outcomes बताना।
  मैंने ऐसे “decision support system” पर काम किया है जिसकी यही responsibility थी, और वह बहुत जल्दी complex हो गया। लोग outcome 100% निश्चित रूप से known होने पर भी उस outcome पर debate करना पसंद करते हैं। उन्हें uncertainty वाली automated emails भी पसंद नहीं आतीं, और यह भी नहीं पसंद आता कि documentation binary choice माँगे जबकि reality में कहीं ज्यादा options होते हैं।
  इस लेख से आगे, उम्मीद है किताब में control के concept पर चर्चा होगी। किसी behavior को document करने के लिए उस behavior पर कुछ हद तक guarantee या enforcement होना चाहिए, ताकि documentation की authority बनी रहे। निजी तौर पर मुझे authority और control की कमी https://www.plainlanguage.gov जैसी writing initiatives का एक common और बड़ा blind spot लगती है।

  • r/technicalwriting पर इस लेख के बारे में जो लिखा था, उसे फिर से quote करूँ तो, Baker के idea में सच में important बात यह है कि technical documentation education की doctrine task-centered approach पर पूरी तरह केंद्रित है।
    अगर professional technical writers का survey किया जाए, तो बहुतों का मानना होगा कि documentation का primary goal, शायद THE primary goal, “users को tasks achieve करने में मदद करना” है।
    Baker का छोटा सा quote Latin sense में “roots की ओर लौटने” के अर्थ में काफी radical है, क्योंकि यह suggest करता है कि हमारी fundamental assumptions में से एक में बड़ी कमी है।
    मुझे व्यक्तिगत रूप से Baker का idea इसलिए interesting लगता है क्योंकि यह current technical documentation से अपेक्षित standards से कहीं ज्यादा ऊँचा standard set करता है। कई docs मान लेते हैं कि task document हो गया तो “mission accomplished”, लेकिन Baker मानो कह रहे हों कि इतना काफी नहीं है।
    tasks तो जाहिर है फिर भी document करने ही होंगे, लेकिन tasks decision बनाने वाली information का subset हैं।
    मुझे याद नहीं कि Baker की किताब ने यहाँ जिस तरह के control की बात की गई है, उस पर चर्चा की थी या नहीं। मेरे लिए यह नया idea है, इसलिए धन्यवाद।
    control का एक concrete example जो दिमाग में आता है, वह यह है: मेरे docs का बड़ा हिस्सा दूसरे open-source projects के pages पर depend करता है, और अगर उन external pages की quality खराब है, तो संभव है कि उन्हें improve करना भी मेरी responsibility होनी चाहिए। कई लोग अपनी site के बाहर की documentation को अपनी responsibility से बाहर मान सकते हैं, लेकिन अगर सच में decisions support करने हैं, तो documentation कौन host कर रहा है, यह important नहीं है।
    शायद अच्छे open-source citizen की तरह रहने के attitude से बहुत कुछ सीखा जा सकता है।