Google की Design Docs दस्तावेज़-लेखन संस्कृति (2020)

 (industrialempathy.com)
4 पॉइंट द्वारा GN⁺ 2024-05-08 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • Google में Design Doc वह दस्तावेज़ है जो कोडिंग से पहले समस्या का संदर्भ, high-level implementation strategy और मुख्य design decisions को व्यवस्थित करता है, ताकि जब design cost कम हो तब जोखिम घटाए जा सकें
  • दस्तावेज़ का मूल्य तैयार code की व्याख्या से अधिक trade-offs और alternatives को सामने लाने में है, ताकि संगठन समान निर्णय-आधार साझा कर सके
  • अच्छा Design Doc संदर्भ और scope, goals और non-goals, वास्तविक design, सोचे गए alternatives, और security, privacy, observability जैसे cross-cutting concerns को project के अनुरूप शामिल करता है
  • अगर design पहले से स्पष्ट है या दस्तावेज़ सिर्फ implementation steps की सूची देता है, तो Design Doc लिखने और review करने का overhead उसके लाभ से अधिक हो सकता है
  • दस्तावेज़ writing, review, implementation के दौरान updates, maintenance और learning तक चलता है; release से पहले design बदलता है तो दस्तावेज़ को भी साथ में update करना बेहतर है

Design Doc की भूमिका

  • Google में Design Doc software system या application के मुख्य authors द्वारा coding project शुरू करने से पहले बनाया जाने वाला काफी informal document है
  • इसमें high-level implementation strategy और प्रमुख design decisions होते हैं, लेकिन सिर्फ decisions की सूची से अधिक यह दिखाने वाले trade-offs महत्वपूर्ण हैं कि वे choices क्यों किए गए
  • Software engineering का उद्देश्य code production अपने-आप में नहीं, बल्कि problem solving है; इसलिए project की शुरुआत में unstructured text, code की तुलना में अधिक संक्षिप्त और समझने में आसान हो सकता है
  • Design Doc development lifecycle में कई भूमिकाएं निभाता है
    • change cost कम होने पर design issues जल्दी पहचानता है
    • संगठन के भीतर design consensus बनाता है
    • security, privacy, observability जैसे cross-cutting concerns छूटने नहीं देता
    • senior engineers के ज्ञान को संगठन में फैलाता है
    • design decisions की organizational memory छोड़ता है
    • designer के technical portfolio को summarize करने वाला output बनता है

Design Doc की बुनियादी संरचना

  • Design Doc के लिए कोई strict template नहीं है, और पहला सिद्धांत यह है कि किसी specific project के लिए सबसे उपयुक्त format चुना जाए
  • फिर भी अक्सर उपयोगी structure को context और scope, goals और non-goals, actual design, considered alternatives, cross-cutting concerns, और उचित length के रूप में व्यवस्थित किया जा सकता है

  • संदर्भ और scope

    • नया system जिस environment में होगा और वास्तव में क्या बनाया जाएगा, इसका rough overview देता है
    • यह requirements document नहीं है, इसलिए concise होना चाहिए और reader को जल्दी background समझाने पर focus करना चाहिए
    • कुछ prior knowledge assume किया जा सकता है, और details को links से जोड़ा जा सकता है
    • इस section को objective background facts पर focus करना चाहिए

  • Goals और non-goals

    • system के goals और कभी-कभी उनसे भी अधिक महत्वपूर्ण non-goals को छोटी bullet list में व्यवस्थित करता है
    • non-goals, “system crash नहीं होना चाहिए” जैसे goal के simple negation नहीं होते, बल्कि वे items हैं जो goal हो सकते थे लेकिन स्पष्ट रूप से exclude किए गए हैं
    • database design में ACID compliance goal है या non-goal, यह जानना एक अच्छा example है
    • non-goal होने पर भी अगर goal achieve करने में बाधा बनने वाला trade-off न हो, तो उस property को देने वाला solution चुना जा सकता है

वास्तविक design लिखने का तरीका

  • actual design section overview से शुरू होकर details तक जाना चाहिए
  • Design Doc software design में आए trade-offs को record करने की जगह है
  • context के facts और goals/non-goals की requirements के आधार पर solution propose करना चाहिए, और दिखाना चाहिए कि कोई particular solution goals को सबसे अच्छे से क्यों satisfy करता है
  • document format का advantage यह है कि problem set के हिसाब से expression style लचीले ढंग से चुना जा सकता है

  • System context diagram

    • कई documents में system-context-diagram उपयोगी हो सकता है
    • यह diagram system को बड़े technical environment के हिस्से के रूप में दिखाता है, ताकि reader अपने जाने-पहचाने environment में नए design को समझ सके

  • API और data storage

    • अगर design किया जा रहा system API expose करता है, तो API को sketch करना आम तौर पर अच्छा होता है
    • formal interface या data definitions को ज्यों का त्यों copy-paste करने से बचना चाहिए
    • ऐसी definitions लंबी हो सकती हैं, अनावश्यक details शामिल कर सकती हैं, और जल्दी outdated हो सकती हैं
    • design और trade-offs से संबंधित हिस्सों पर focus करना चाहिए
    • data store करने वाले systems को यह बताना चाहिए कि data कैसे और किस approximate form में store होगा
    • पूरी schema definition paste करने के बजाय design judgments से संबंधित हिस्सों को explain करना बेहतर है

  • Code और pseudocode

    • Design Doc में code बहुत कम रखना बेहतर है
    • नए algorithm को explain करने के मामलों को छोड़कर pseudocode भी कम ही इस्तेमाल करना चाहिए
    • अगर कोई prototype यह दिखाता है कि design implementable है, तो उसे उचित रूप से link किया जा सकता है

Constraints की degree document का रूप बदलती है

  • software design और Design Doc के रूप को प्रभावित करने वाले मुख्य factors में से एक solution space की constraint degree है
  • एक छोर पर greenfield software project होता है, जिसमें केवल goals होते हैं और solution कुछ भी हो सकता है
    • ऐसे documents व्यापक scope cover कर सकते हैं, लेकिन manageable set of solutions तक narrow करने के लिए rules जल्दी define करने चाहिए
  • दूसरे छोर पर ऐसे systems होते हैं जहां possible solutions अच्छी तरह defined होते हैं, लेकिन उन solutions को मिलाकर goals कैसे achieve किए जाएं यह स्पष्ट नहीं होता
    • यह बदलने में कठिन legacy system हो सकता है
    • यह ऐसी library design हो सकती है जिसे host programming language की constraints के भीतर काम करना हो
  • ऐसे cases में अपेक्षाकृत आसानी से किए जा सकने वाले tasks list किए जा सकते हैं, लेकिन goals achieve करने के लिए उन्हें creatively combine करना पड़ता है
  • अगर कई solutions में से कोई भी perfect नहीं है, तो document को identified trade-offs के आधार पर best approach चुनने पर focus करना चाहिए

Alternatives और cross-cutting concerns

  • सोचे गए alternatives

    • यह section उन alternative designs की सूची देता है जिनसे समान result reasonably achieve किया जा सकता था
    • focus इस पर होना चाहिए कि हर design कौन-से trade-offs बनाता है, और वे trade-offs final choice तक कैसे ले गए
    • जो solutions नहीं चुने गए उन्हें concise रखा जा सकता है, लेकिन यह section document में बहुत महत्वपूर्ण है
    • इसे दिखाना चाहिए कि reader जिन अन्य solutions के बारे में सोच सकता है, वे project goals के आधार पर कम desirable क्यों हैं

  • Cross-cutting concerns

    • संगठन इस section के जरिए सुनिश्चित कर सकता है कि security, privacy, observability जैसे cross-cutting concerns हमेशा consider हों
    • आम तौर पर यह एक छोटा section होता है जो बताता है कि हर concern design को कैसे प्रभावित करता है और उसे कैसे handle किया जाता है
    • teams को तय करना चाहिए कि अपनी situation में किन concerns को standard माना जाए
    • Google projects में importance के कारण अलग privacy Design Doc की requirement होती है, और privacy व security के लिए dedicated reviews होते हैं
    • review completion project release के समय तक required होता है
    • best practice यह है कि design शुरू से इन्हें reflect करे, इसलिए privacy और security teams के साथ जितना जल्दी हो सके collaborate किया जाए
    • अगर उस topic पर dedicated document है, तो central Design Doc details repeat करने के बजाय उसे reference कर सकता है

Length और कब लिखना जरूरी नहीं

  • उचित length

    • Design Doc पर्याप्त detailed होना चाहिए, लेकिन इतना छोटा भी कि busy लोग वास्तव में पढ़ सकें
    • बड़े projects में लगभग 10–20 pages ठीक जगह लगती है
    • अगर इससे बहुत लंबा हो जाए, तो problem को अधिक manageable sub-problems में बांटना बेहतर हो सकता है
    • 1–3 pages का mini Design Doc भी संभव है
    • यह incremental improvements या agile project के sub-tasks के लिए खास तौर पर उपयोगी है
    • यह लंबे document जैसी steps follow करता है, लेकिन अधिक concise होता है और सीमित problem set पर focus करता है

  • कब लिखना जरूरी नहीं

    • Design Doc लिखने में overhead होता है
    • लिखना है या नहीं, यह इस पर निर्भर है कि design consensus, documentation, senior review जैसे benefits document creation cost से अधिक हैं या नहीं
    • मुख्य decision criterion यह है कि design problem ambiguous है या नहीं
    • ambiguity problem complexity, solution complexity, या दोनों के कारण हो सकती है
    • अगर ambiguity नहीं है, तो document-writing process का value कम है
    • अगर document वास्तव में implementation manual है, तो Design Doc की जरूरत नहीं हो सकती
    • अगर वह सिर्फ “इसे ऐसे implement करूंगा” कहता है और trade-offs, alternatives, decision-making explanation नहीं देता, तो शायद सीधे program लिखना बेहतर होता
    • अगर solution इतना स्पष्ट है कि trade-offs नहीं हैं, तो document का value कम है
    • Design Doc लिखने और review करने का overhead prototyping और fast iteration से मेल नहीं खा सकता
    • agile methodology follow करने का मतलब यह नहीं कि ज्ञात problem के solution पर ठीक से विचार करने की जरूरत नहीं है
    • prototyping खुद Design Doc writing का हिस्सा हो सकती है, और “try किया और काम करता है” design choice का मजबूत evidence हो सकता है

Design Doc का lifecycle

  • Design Doc का lifecycle चार चरणों से बना है
    1. writing और fast iteration
    2. review
    3. implementation और iteration
    4. maintenance और learning

  • Writing और fast iteration

    • document author अकेले या co-authors के साथ लिखता है
    • इसके बाद problem space को सबसे अच्छी तरह जानने वाले colleagues के साथ share कर तेजी से iterate किया जाता है
    • colleagues के clarification questions और suggestions document को अपेक्षाकृत stable first version तक ले जाते हैं
    • Google में कुछ engineers और teams version control और code review tools से document बनाना पसंद करते हैं, लेकिन अधिकांश Design Docs Google Docs में लिखे जाते हैं और collaboration features का खूब उपयोग करते हैं

  • Review

    • review phase में document को original author और close collaborators से व्यापक audience के साथ share किया जाता है
    • review बहुत value add कर सकता है, लेकिन overhead trap भी बन सकता है, इसलिए सावधानी से handle करना चाहिए
    • हल्का तरीका है document को व्यापक team mailing list पर भेजना ताकि लोगों को देखने का मौका मिले
    • discussions मुख्य रूप से document के comment threads में होती हैं
    • भारी तरीका formal design review meeting है, जहां author document को senior engineer audience के सामने present करता है
    • Google की कई teams ऐसी reviews के लिए regular meetings रखती हैं
    • ऐसी meeting का इंतजार development process को काफी slow कर सकता है
    • सबसे महत्वपूर्ण feedback सीधे मांगकर और broader review को progress blocker न बनाकर इसे कम किया जा सकता है
    • जब Google छोटी company थी, तब design को एक central mailing list पर भेजना और senior engineers द्वारा समय मिलने पर review करना customary था
    • इस approach का advantage था कि पूरी company में अपेक्षाकृत uniform software design culture बनती थी
    • engineering organization बहुत बड़ा होने पर centralized approach maintain करना कठिन हो गया
    • review का मुख्य value यह है कि organization का combined experience design में reflect होने का अवसर बने
    • खास तौर पर observability, security, privacy जैसे cross-cutting concerns को design में consider कराने में review phase लगातार मदद करता है
    • review का core value issue discovery अपने-आप में नहीं, बल्कि development lifecycle की शुरुआत में, जब change cost कम होती है, issues के discover होने में है

  • Implementation और iteration

    • जब यह confidence हो जाए कि additional review design में बड़े changes की मांग करने की संभावना कम है, तब implementation शुरू करने का समय है
    • जब plan reality से टकराता है, तो defects, unhandled requirements, और गलत साबित हुई assumptions सामने आ सकती हैं, और design changes की जरूरत पड़ सकती है
    • इस case में Design Doc update करना strongly recommended है
    • rule of thumb के रूप में, अगर designed system अभी release नहीं हुआ है, तो document जरूर update करना चाहिए
    • reality में लोग documents को ठीक से update नहीं कर पाते, और अन्य practical reasons से changes अक्सर नए document में अलग हो जाते हैं
    • नतीजतन यह एक coherent document के बजाय amendments लगी हुई US Constitution जैसी स्थिति बन सकता है
    • original document से ऐसे amendment documents को link कर देने से बाद में maintenance programmer को Design Doc archaeology के जरिए target system समझने में बहुत मदद मिलती है

  • Maintenance और learning

    • जब Google engineer पहली बार किसी system से रूबरू होता है, तो अक्सर पहला सवाल होता है: “Design Doc कहां है?”
    • बाकी documents की तरह Design Doc भी समय के साथ reality से अलग होने की tendency रखता है, लेकिन system बनाने की thought process सीखने के लिए यह अक्सर सबसे accessible entry point होता है
    • author के लिए 1–2 साल बाद अपना Design Doc फिर से पढ़ना अच्छा है
    • देखें कि क्या सही निकला
    • देखें कि क्या गलत निकला
    • सोचें कि आज होते तो क्या अलग decision लेते
    • इन सवालों के जवाब देने की process engineer के रूप में grow करने और समय के साथ software design capability improve करने में मदद करती है

कब Design Doc से शुरू करना है, यह तय करना

  • Design Doc software project की कठिन problems को solve करते समय clarity पाने और consensus बनाने का अच्छा तरीका है
  • prior investigation से coding के उन dead ends को घटाकर cost बचाई जा सकती है जिन्हें टाला जा सकता था
  • साथ ही writing और review में time लगता है, इसलिए cost भी होती है
  • निम्न questions पर विचार किया जा सकता है
    • क्या सही software design uncertain है, और confidence पाने के लिए पहले से time लगाना उचित है?
    • क्या senior engineers को design phase में शामिल करना मददगार है, जो शायद हर code change review न कर सकें?
    • क्या software design ambiguous या विवादित है, इसलिए organizational consensus valuable है?
    • क्या team design में privacy, security, logging या अन्य cross-cutting concerns कभी-कभी भूल जाती है?
    • क्या organization में legacy system design पर high-level insight देने वाले document की strong need है?
  • अगर इन questions में से 3 या अधिक का जवाब “हां” है, तो Design Doc अगले software project की शुरुआत करने का अच्छा तरीका होने की संभावना अधिक है

संबंधित पढ़ाई

1 टिप्पणियां

 
GN⁺ 2024-05-08
Hacker News की राय

  • मैंने Google की डिज़ाइन डॉक्यूमेंट संस्कृति की वजह से कंपनी छोड़ दी
    जॉइन करने के तुरंत बाद, मैंने एक ऐसे अपेक्षाकृत मामूली काम पर बहुत हाई-लेवल में व्यवस्थित डॉक्यूमेंट लिखा, जिसे मैं दूसरे product areas में कई बार कर चुका था। एक सहकर्मी ने मुझे अलग से बुलाकर कहा, “यहाँ हम ऐसे नहीं करते।”
    मैंने जो तरीका सुझाया था वह recommended तरीके का बस एक छोटा-सा variant था, लेकिन उन्होंने कहा, “इस काम को करने के और तरीकों का मूल्यांकन करो।” वजह पूछने पर जवाब मिला, “इससे दिखता है कि तुमने व्यापक रूप से विचार किया है।”
    Google में नकली काम निश्चित रूप से मौजूद है, और काश मैं किसी दूसरी टीम में गया होता

    • आप जिस व्यवहार को reward करते हैं, वही असली व्यवहार बन जाता है। शुरुआती दौर में design docs दिशा पर सहमति बनाने और सहकर्मियों को context देने का tool थे, लेकिन बाद में headcount exponential तरीके से बढ़ने पर नेक-नीयत managers ने performance evaluation के लिए docs लिखने को कहा, और चीज़ें उलझने लगीं
      Google संस्कृति खुद की नकल करने वाला cargo cult बन गई
      Google के बाद जिन कुछ कंपनियों में मैं गया, वे promotion process पर विस्तार से चर्चा करने से कतराती थीं, क्योंकि उन्होंने देख लिया था कि जब लोग उस process के हिसाब से micro-optimize करते हैं तो क्या होता है
    • संभव है यह पुरानी और mature products संभालने वाली teams की बनाई संस्कृति की वजह से हो। ऐसी जगहों पर किसी मामूली project को launch करने के लिए भी कम से कम 10 लोगों के साथ, और मेरे मामले में आम तौर पर 20–30 लोगों के साथ, collaborate करना पड़ता है; impact scope 100–500 लोगों तक पहुँच जाता है
      सब व्यस्त होते हैं, इसलिए हर किसी से हल्की-फुल्की 1:1 बात नहीं की जा सकती, और अगर stakeholder review ठीक से न मिले तो नाराज़ लोग आकर launch rollback कराने की संभावना रहती है
      इस context में design doc information-dense topics के लिए async communication tool है। अगर product सफल होता है, तो 10 साल बाद join करने वाले लोगों से भी आप इसी doc के ज़रिए बातचीत करते हैं
      2010 के किसी random design doc ने, जो आज भी परेशान करने वाले अजीब फैसलों को समझाता था, मुझे कई बार बचाया है। फुर्तीली छोटी teams या कम complex tasks के लिए यह शायद फिट न बैठे, लेकिन engineering culture में यह cargo cult बन गया हो तब भी, आम तौर पर इसके अपने कारण और context होते हैं
    • अगर सरल और स्पष्ट तरीका व्यावहारिक रूप से सिर्फ एक ही हो, तो 1-page doc लिखते हैं, लेकिन इस हिस्से में मैं Google का पक्ष लेना चाहूँगा
      अगर आप कुछ design कर रहे हैं और विचाराधीन solution सिर्फ एक है, तो या तो design है ही नहीं या वह पर्याप्त रूप से thorough नहीं है। विकल्प और trade-offs ही design बनाते हैं
    • जहाँ मैं काम करता हूँ वहाँ उलटी समस्या है। जब किसी अपेक्षाकृत मामूली काम के लिए बहुत high-level design doc लिखने को कहा जाता है, तो जवाब मिलता है, “इसे करने के कई तरीके हैं, इसलिए ऐसे docs बेकार हैं; काम मामूली है, तो engineer उनमें से कोई एक चुनकर कर दे।”
      इनमें से कई लोग external consultants हैं जो कंपनी के साथ 15 साल से अधिक समय से काम कर रहे हैं, इसलिए क्योंकि वही लोग वही काम करते आए हैं, कुछ हद तक standard पहले से है। फिर भी वे “अगर लोग standard follow न करें तो क्या होगा” वाला straw man खड़ा करने की कोशिश करते हैं
      नतीजतन design docs या तो होते ही नहीं हैं या बहुत पुराने हो चुके होते हैं, और कंपनी हर साल उन्हीं consultants को फुलाए हुए खर्च पर hire करती रहती है
    • दूसरी team में था तो मुझे ऐसा ही लगा था। ऐसा लगता था जैसे documents लिखने के लिए documents लिखने की अपेक्षा की जा रही हो, यानी यह cargo cult engineering के करीब था
      अब मैं ऐसी team में हूँ जहाँ 15+ साल के tenure वाले पुराने Googlers कई हैं, और design docs सिर्फ तब होते हैं जब ज़रूरत हो। जैसे कई systems में फैला मामला हो, या trade-offs इतने अधिक हों कि complexity साफ़ हो। बाकी मामलों में बस “CLS लिखो” जैसा होता है

  • Google में design docs promotion packet में जाने वाली मुख्य सामग्री होते हैं, इसलिए लगता है समस्या वहीं से पैदा होती है
    इसलिए दस्तावेज़ अपने मूल पाठक—उस सिस्टम पर काम करने वाले लोगों—से ज़्यादा promotion committee को ध्यान में रखकर लिखे जाते हैं

    • जिन भी कंपनियों में अब तक काम किया, हर जगह ऐसा ही था। करियर, प्रतिष्ठा या क्षमता से ज़्यादा exposure पर निर्भर करता है। Design docs ऊपर के लोगों को बहुत साफ़ दिखते हैं
      हर नई कंपनी में जाते ही मैं design docs लिखना शुरू करने का सुझाव देता हूँ, और इससे तुरंत management पर अच्छा impression पड़ता है :)
    • इसी वजह से, ज़रूरत न होने पर भी कई दस्तावेज़ ज्यादा जटिल design format अपनाने लगते हैं। मकसद उन लोगों से performance score ज़्यादा पाना होता है जिनके पास दस्तावेज़ बस सरसरी तौर पर देखने का समय होता है
      मैंने जो कई दस्तावेज़ पढ़े, वे ऐसे लगे जैसे desired decision पहले से तय था, और document की शुरुआत में उस फैसले को सही दिखाने के लिए गढ़े गए दो या उससे ज़्यादा विकल्प जोड़ दिए गए थे। एक बहुत ज़्यादा सरल, दूसरा बेवजह over-engineered—ऐसा contrast बनाकर फिर वह विकल्प चुना जाता था जो reasonable लगे
    • Developers खुलकर कहते हैं कि वे design docs promotion committee के लिए लिखते हैं। वही लक्ष्य है, बाकी सब secondary है
      कौन-सा design doc promotion packet में इस्तेमाल होगा, यह पता नहीं होता, इसलिए सबसे छोटा काम भी design doc के रूप में दर्ज किया जाता है। 1-page design doc की अवधारणा तो है, पर आम तौर पर वह एक पेज से बढ़कर कई पेजों का हो जाता है
      1 हफ्ते के project के लिए भी design doc लिखा जाता है, और कभी-कभी मुझे 20, 30, 40 पन्नों के design docs review करने पड़े, जो दूसरी कंपनी में एक JIRA ticket में खत्म हो जाते
      बहुत से लोगों ने यह सीखा है कि promotion committee “लेखक ने अकेले लिखा हुआ दस्तावेज़” देखना चाहती है, और यह सही हो या नहीं, यह विश्वास हर चीज़ को धीमा बनाता है और cross-learning को रोकता है। मैंने software engineers को एक quarter से ज़्यादा समय तक isolated रहकर सिर्फ design doc लिखते भी देखा है
      Design doc में असली design ही मुख्य होना चाहिए, लेकिन बाकी 99% problem definition होता है। Review के दौरान problem definition सुधारते-सुधारते design को छोड़कर document का ज़्यादातर हिस्सा फिर से लिखना पड़ा—ऐसा बहुत बार हुआ
      सबसे खराब स्थिति तब होती है जब problem definition बेहतर करने पर कोई सरल समाधान सामने आ जाता है जिसे complex design की ज़रूरत नहीं होती। लेखक ने complex design में बहुत समय लगाया होता है, और ऐतिहासिक रूप से कई committees ने ऐसी complexity को promotion का आधार माना है, इसलिए वे सरल समाधान का विरोध करते हैं
      मैंने ऐसे design docs भी देखे जिनमें कोई alternative था ही नहीं। वे बस मेहनत-तलब तरीके से लिखी गई चीज़ों की list थे—क्या करना है या कोई क्या करना चाहता है
      ऐसा होते-होते design doc धुंधले तौर पर bug tracking system जैसा बन जाता है। हर कोई अपने design doc पर काम कर रहा होता है, bugs पर नहीं। क्योंकि bugs से promotion नहीं मिलता
      नई team में जाने पर कहा जाता है कि बस design docs पढ़ लो, लेकिन असल में वे अक्सर centrally tracked नहीं होते। कई teams में design docs team या project के स्वामित्व में नहीं, बल्कि individual ownership में होते हैं, क्योंकि इससे यह सुनिश्चित किया जा सकता है कि किसी और ने contribute नहीं किया; और यह भी promotion committee की वजह से है
      कई design docs ऐसे भी होते हैं जिनकी access नहीं होती—इसलिए नहीं कि वे top secret हैं, बस व्यवस्था ही ऐसी है। Team में सिर्फ दो-तीन design docs नहीं होते, बल्कि पढ़ने के लिए ढेर लगा होता है। Google में job switching cycle करीब 2 साल की है, ऐसे में कई दस्तावेज़ समय के साथ गायब हो जाते हैं
      यह कुछ वैसा ही है जैसे किसी दूसरी कंपनी में नई team में आए व्यक्ति से कहा जाए कि “जो चाहिए वह सभी closed bugs पढ़कर या main branch के हर commit message को पढ़कर मिल जाएगा”
      किसी और जगह होता तो lunch के बाद पकड़कर team के साथ whiteboard के सामने कुछ घंटों तक समस्या define की जाती। Senior लोग juniors को real time में सिखाते कि ऐसी समस्या के बारे में कैसे सोचना चाहिए, और तेज़ी से iterate करते
      ज़्यादातर चीज़ें bug tracking system में लिखी जातीं, या अगर काम बड़ा होता तो project wiki या folder में डालकर उसे सबकी shared ownership बना दिया जाता
      ऊपर की सारी समस्याएँ सुधारी जा सकती हैं, और सचमुच उन्हें सुधारने की कोशिश भी की है, लेकिन culture धीरे-धीरे बदलता है। Design doc की अवधारणा अपने आप में अच्छी है, लेकिन इसमें pitfalls हैं, और Google में कई लोग जिस तरह इसका इस्तेमाल करते हैं, वह सही जवाब नहीं है
    • इतना ही नहीं, यह bureaucratic requirements पूरी करने के लिए भी होता है। दूसरे लोगों के documents पर comment करके leadership दिखाना भी
      मुझे ऐसे design docs की कमी खलती है जिनकी value उनकी cost से ज़्यादा हो
    • मुझे ठीक से समझ नहीं आता कि फर्क क्या है। शायद team members को जितना context चाहिए उससे ज़्यादा देना, या समस्या को असल से ज़्यादा complex दिखाना
      कुल मिलाकर, मैंने वह strategy काम करते हुए नहीं देखी
      दूसरी ओर, context देने के लिए लंबे documents जरूर थे—team ने क्या किया, क्या कर रही है, समस्या क्या है आदि को व्यवस्थित करने वाले—और वे लंबे और exaggerated होने की tendency रखते थे

  • मैं जिस कंपनी की बात हो रही है, वहीं काम करता हूँ, लेकिन मेरा अनुभव लेखक जैसा नहीं है
    डिजाइन डॉक्यूमेंट्स कई तरह के होते हैं, और उनमें से कोई भी मुझे उपयोगी नहीं लगा। Google में उपयोगी डिजाइन डॉक्यूमेंट देखना मेरे लिए दुर्लभ रहा है। डिजाइन डॉक्यूमेंट ऐसे लगते हैं जैसे वे अत्यधिक प्रक्रिया-उन्मुख इंजीनियरों के लिए हों
    मैंने जो प्रकार देखे हैं, वे मोटे तौर पर ऐसे हैं: प्रमोशन के लिए डिजाइन डॉक्यूमेंट यह नहीं बताते कि वे क्या हल करने की कोशिश कर रहे हैं; वे सिर्फ बताते हैं कि यह प्रोजेक्ट कितना शानदार है और कंपनी को कितना बेहतर बनाएगा। तार्किक निष्कर्ष यह होता है कि लेखक को प्रमोशन मिलना चाहिए
    टर्बो एन्कैप्सुलेटर डिजाइन डॉक्यूमेंट ऐसे technical chatter से भरे होते हैं जिनमें पहली बार दिखने वाले शब्द होते हैं, इसलिए अगर आप टीम के senior नहीं हैं तो समझ नहीं सकते। कभी-कभी मुझे यह भी यकीन नहीं होता कि senior लोग भी समझते हैं या नहीं
    नए ग्रेजुएट का डिजाइन डॉक्यूमेंट ऐसा डॉक्यूमेंट होता है जिसमें सामग्री तो नहीं होती, लेकिन कॉलेज से अभी-अभी निकला व्यक्ति क्या साबित करना चाहता है, इसे यथासंभव लंबा बनाया गया होता है। यह जानकारी नहीं पहुँचाता, और अक्सर पहले से लिखे गए कोड को बड़े पैमाने पर copy-paste करके करीब 70 पेज भर देता है
    गढ़े हुए तथ्यों वाला डिजाइन डॉक्यूमेंट “सब जानते हैं”, “सब ऐसा कहते हैं” से भरा होता है। राजनेताओं जितना खुले तौर पर नहीं, लेकिन “यह good practice का पालन करता है”, “यह software धीमा है, इसलिए…” जैसे तरीकों से अपना डिजाइन आगे बढ़ाता है। किसने good practice परिभाषित की, वह good practice क्यों है, क्या धीमा है, क्या मापा गया है, क्या यह end user की अनुभूति है—ये सब गायब होते हैं
    मैंने जितने डिजाइन डॉक्यूमेंट देखे हैं, उनमें से 99% ऐसे ही थे। अपवाद हैं, लेकिन मेरे अनुभव में बहुत दुर्लभ। यह देखकर हैरानी होती है कि लेखक इस practice को बढ़ावा दे रहा है। हालांकि वह engineer नहीं बल्कि director था, इसलिए उस भूमिका में डिजाइन डॉक्यूमेंट शायद समझ में आते हों; फिर भी मुझे नहीं पता कि ऐसे लोग क्या value देते हैं
    [1] https://en.wikipedia.org/wiki/Turbo_encabulator

    • लगता है यह बदल गया है। मैंने 2006~2014 में वहाँ काम किया था, और उस समय ज्यादातर डिजाइन डॉक्यूमेंट उपयोगी थे और लेख में बताए गए basic structure का पालन करते थे। हालांकि system context diagram नहीं होते थे
      शुरुआत में जो बात ध्यान में आई वह यह थी कि Google Docs में रखे गए डिजाइन डॉक्यूमेंट version control repository में मौजूद दस्तावेजों की तुलना में कम quality के होते थे। यह लिखे जाने के समय का proxy indicator था या code review process Docs editing से ज्यादा strict था, यह नहीं जानता
      जब मैंने एक बड़ा डिजाइन डॉक्यूमेंट लिखा था, शायद करीब 40 पेज का, तो परंपरा के अनुसार उसे हाथ से लिखे HTML में बनाया और code review system से गुजारा। उसे central mailing list और web server पर भी डाला, और employee number 3 से feedback मिलना भी अच्छा था। central location में category के हिसाब से sorted होने के कारण उसे ढूँढना आसान था
      उस समय मुझे याद नहीं कि कोई एक डिजाइन डॉक्यूमेंट promotion में महत्वपूर्ण होने जितना बड़ा weight रखता था। promotion किसी खास deliverable के बजाय overall impact के बारे में होना चाहिए था। बेशक system में बड़ी खामियाँ थीं और बुरे अर्थ में हैरान करने वाले फैसले भी अक्सर आते थे, लेकिन तब performance review के लिए optimized डिजाइन डॉक्यूमेंट पढ़ने की याद नहीं है
      अगर आपको शुरुआती हाथ से लिखे HTML डिजाइन डॉक्यूमेंट्स का संग्रह वाली website मिल जाए, तो उसे देखने की सलाह दूँगा। शायद उस समय, जब वे systems active थे, वह और भी उपयोगी लगती
      SmartASS जैसे कुछ पुराने दस्तावेज underlying equations और models की विस्तृत व्याख्या से भरे थे, और वे यह समझने में बहुत मददगार थे कि चीजें कैसे काम करती हैं और वह approach क्यों चुनी गई। बाद में मेरे अपने design work पर भी उनका असर पड़ा। मैं director नहीं था, बस एक engineer था, और वे सच में मददगार थे
      chromium.org website से linked Chrome design docs में भी कुछ ऐसे हैं, जिन्होंने अतीत में structure समझने में मदद की
    • जहाँ senior की तुलना में junior roles अपेक्षाकृत ज्यादा होते हैं, वहाँ मैंने design docs को अच्छी तरह काम करते देखा है
      यह junior developer को पहले से solution सोचने और decisions justify करने के लिए मजबूर करता है, और senior developer को उन decisions को validate करने और asynchronous feedback देने देता है
      हालांकि मैंने हमेशा startups में काम किया है, इसलिए 30~40 से ज्यादा engineers वाली organization में कभी काम नहीं किया। Big Tech अलग होगा, लेकिन मेरा अनुभव सकारात्मक रहा है
    • लगता है आपने एक चीज छोड़ दी। कृपया अब मुझे coding शुरू करने दो डॉक्यूमेंट भी होता है
    • technical documents—चाहे design docs हों या छोटे documents—का उपयोग मुझे सरल लगता है। जब आप उस point पर पहुँच जाते हैं जहाँ project की सभी details एक साथ दिमाग में नहीं रख सकते, तो document लिखना चाहिए
      इसी तरह, अगर किसी दूसरे engineer को समझाने में ज्यादा समय लगता है, कम से कम 30 मिनट भी, तो समय बचाने के लिए document लिखना चाहिए
      कोई कैसे सोच सकता है कि document लिखने की बिल्कुल जरूरत नहीं है, यह समझ नहीं आता
    • मेरे अनुभव में दूसरा प्रकार अक्सर इस अर्थ में था: “मैं क्या कर रहा हूँ और इस problem को कैसे solve कर रहा हूँ, यह team या tech leader से communicate करना है”
      बाद में promotion की तैयारी करते समय, category 2 वाले document में पर्याप्त context जोड़कर उसे category 1 बना दिया जाता है

  • documentation आम तौर पर अच्छी चीज है, लेकिन यह approach flawed लगती है
    कहा जाता है कि “coding project शुरू करने से पहले” software system या application का मुख्य author एक अपेक्षाकृत informal document बनाता है, लेकिन design खुद coding project है और दोनों एक ही काम हैं
    code commit करने से पहले कागज पर design पूरी तरह solve किया जा सकता है—यह विचार गलत है। design doc approach भी दरअसल मानता है कि शुरुआत में थोड़ा code लिखना पड़ता है, लेकिन इसे “design की implementability दिखाने वाला prototype” कहकर strict boundary में रखना चाहता है
    upfront design document की बड़ी विशेषता यह है कि full-scale coding से पहले लोगों को nitpick करने, यानी review करने की अनुमति मिल जाती है। मेरे अनुभव में ऐसा होने पर document बढ़ता ही जाता है—और अधिक caveats और बेकार alternative discussions जुड़ती जाती हैं—और वह design document से ज्यादा “कृपया अब मुझे यह बनाने दो” document बन जाता है
    अगर कोई महत्वपूर्ण architecture issue है जिसमें direction change चाहिए, तो detailed design document बनाकर reject होने से बेहतर है कि पहले ही सही लोगों से बात की जाए और collaborate किया जाए
    अगर इसे “अपेक्षाकृत informal document” वाले विचार के करीब रखा जाए और आगे बढ़ते हुए document update किया जाए, तो यह सच में उपयोगी हो सकता है। क्योंकि इससे working system और useful documentation साथ-साथ बन सकते हैं। हालांकि वह design document से ज्यादा एक continuous और collaborative process के हिस्से के रूप में documentation करने जैसा है

    • अगर project पर्याप्त बड़ा और अच्छी तरह सोचा हुआ है, तो कुल work की तुलना में ज्यादा अतिरिक्त cost के बिना architecture changes को reflect किया जा सकता है

  • मैं Googler हूँ। मैंने कई पेपर भी निकाले हैं, लेकिन पहले design docs लिखना पसंद नहीं था। कुछ साल पहले से मुझे इसके मुख्य फायदे समझ में आए
    यह आइडिया के तुरंत सामने दिखने वाले हिस्से को दिमाग से खाली कर देता है, ताकि गहरे हिस्सों और उत्पादक विचारों पर जाया जा सके
    खामियाँ ज़्यादा साफ दिखती हैं, खासकर खुद मुझे
    विचार साझा करना आसान हो जाता है, खासकर दूसरे offices के लोगों के साथ। वे आम तौर पर बहुत अच्छा feedback देते हैं
    सिर्फ coding शुरू करने की तुलना में यह जरूरी काम की मात्रा का कहीं बेहतर अंदाजा देता है
    coding से पहले जो चीजें सीखनी हैं—पास के systems या सही technology choice वगैरह—वे भी अक्सर सामने आ जाती हैं
    promotion के लिए भी अच्छा है, लेकिन सफल project उससे बेहतर है। लोग अक्सर कहते हैं कि मेरे docs उपयोगी हैं, इसलिए लगता है कि कोई सही रास्ता मिल गया है

    • मेरा भी यही अनुभव है। design docs का सबसे बड़ा लाभार्थी मेरी सोचने की प्रक्रिया थी। पूर्व Googler हूँ

  • क्या यह सच में काम करता है? क्या यह alternatives से बेहतर है? उस पर चर्चा कहाँ है?
    जब मैं Amazon में काम करता था, design docs की संस्कृति शानदार थी। अगली job में ऐसा लगा कि Google की engineering culture या SF की सामान्य startup culture उधार ली गई है, लेकिन design docs की प्रक्रिया बेकार मजाक जैसी थी

    • design docs चर्चा का माध्यम हैं। विचार यह है कि intent, motivation, और यह कि दूसरे alternatives क्यों नहीं चुने गए—इन सबको सबसे प्रभावी तरीके से बताया जाए
      यह व्यापक work culture से जुड़ा एक mechanism है। अगर आप अकेले काम कर रहे हैं तो यह एक luxurious exercise है, और अगर बहुत बड़ी team है तो यह पूरी team की अधिक expertise का उपयोग करवाता है और documentation का काम भी करता है
      failure modes कुछ तरह के होते हैं। outcome के बजाय output को महत्व देना एक typical mismatch है। promotion के लिए 40-page docs लिखना—यह तब तक अच्छा काम नहीं करता जब तक मामला बहुत junior स्तर का न हो, जहाँ deep engineering से ज्यादा यह साबित करना हो कि आप sentences जोड़ सकते हैं
      अकेले काम करने वाली teams के लिए यह overkill भी है। दूसरी छोटी teams issues, जैसे Jira, और ideas को align करने के लिए अलग session भर से भी पर्याप्त communication कर सकती हैं
      engineers को भी effective design docs लिखने के तरीके पर onboard किया जाना चाहिए। ऊपर वाले comment में पहली कोशिश को तुरंत तारीफ न मिलने पर हताशा दिखना एक signal हो सकता है
      code के बारे में लिखना कठिन है, और आम तौर पर HN ऐसी practice की तारीफ करता है। अगर आप team में काम करते हैं, तो सावधान रहें अगर आपको लगने लगे कि आपका काम हमेशा ऐसा ही है जिसे साझा करने योग्य docs में समझाने और गहराई से सोचने की जरूरत नहीं होती
    • Amazon की design docs culture में आपको सबसे अच्छा क्या लगा, यह जानने की उत्सुकता है

  • अगर कोई बड़ा investor अपनी पहचान छिपाकर कुछ हफ्तों तक Google engineer के रूप में काम करे, तो वह तुरंत Sundar को हटाने की मांग करने वाला activist investor बन जाएगा
    Google की design docs culture की वजह से जो मानवीय क्षमता बर्बाद होती है, उसका पैमाना लगभग समझ से परे है

    • मुझे लगता है लोग ज्यादातर design docs में लगने वाले effort को बहुत बढ़ा-चढ़ाकर आंकते हैं
      ज्यादातर development बस आगे बढ़ती रहती है, और कभी-कभी CL को justify करना आसान बनाने के लिए जल्दी-जल्दी doc लिख दिया जाता है
      10 में से लगभग एक मामले में कोई बहुत ज्यादा overdo करता दिखता है, लेकिन average software engineer के लिए यह बड़ा time waste नहीं है
    • Carl Icahn ऐसे काम के लिए बिल्कुल सही व्यक्ति हैं। https://www.bloomberglinea.com/english/i-fired-12-floors-of-...
    • मेरी hypothesis है कि late-stage Google को monopoly profits छिपाने के लिए design किया गया है
      अगर आप जितना हो सके उतना पैसा जलाना चाहें, तो शायद company को ठीक इसी तरह design करेंगे

  • design docs culture में सबको अपने काम के लिए justification layer में धकेलने की प्रवृत्ति होती है। justification culture, भले ही colleagues उसे culture के रूप में reinforce करें, innovators के लिए काफी दमनकारी pattern है
    यह system visionary attempts और ambitious projects को रोकने की ओर झुकता है। consensus-driven न होने वाली कोशिशें दबा दी जाती हैं, और अगर आप “allowed norms के बाहर” सोचते हैं तो group आपको punish करता है
    ऐसे systems groupthink पैदा करते हैं, और “हम काम ऐसे करते हैं” वाली tradition-centric प्रकृति मूल रूप से ऐसी स्थिति थोपती है जहाँ दूसरे तरीके से काम करना career के लिए risk बन जाता है
    Silicon Valley में ‘agile’ और ‘design thinking’ terminology में पैक की गई clichés पर निर्भर company cultures हर तरह से मौजूद हैं, और अक्सर वे ‘सही तरीका’ होने का नाटक करने वाली institutionalization के करीब होती हैं, साथ में उस campus तक पहुँचे engineering cult culture variant को socially enforce करने वाले extra elements भी आते हैं
    मैंने गिनती से बाहर ऐसे लोगों से मुलाकात की है जिन्होंने Google में काम करना बहुत comfortable होने के बावजूद इसे career-limiting मानकर छोड़ दिया, और उनकी संख्या कम नहीं है

    • इसलिए वे compensation इतना ज्यादा देते हैं। यह trap है। और वहाँ काम करने की दिखावटी status भी थी, लेकिन अब वह ज्यादातर फीकी पड़ गई है
      आपने वहाँ मेरी frustration को बिल्कुल सही शब्दों में कहा। फिर भी वह compensation फिर से पाना चाहूँगा
      agile की बात करें तो, मैं करीब 20 साल पहले eXtreme Programming के रूप में agile से परिचित हुआ था, और वह आज के SCRUM या उसके नकली cargo cult से बिल्कुल अलग था
      आखिरकार यह principles का एक bundle था जो developers को creative power देता था, managers को methods में दखल देने से रोकता था, और काम करवा देता था। बदले में customer को यह बताने का अधिकार देता था कि क्या, कब और कितनी सीमा तक करना है
      developers खुद estimate करते थे, और principle था “जो जरूरी नहीं है, उसे मत बनाओ।” upfront बड़ा design नहीं होता; refactoring और tests, architecture और design अलग stories या tasks नहीं, बल्कि standard best practices के रूप में ongoing overhead में शामिल होते हैं
      planning meeting में colleagues कमरे में align करते थे, और stories whiteboard पर post-its में न्यूनतम non-technical terms में लिखी जाती थीं। standup में सच में लोग circle में खड़े होकर इतने छोटे updates देते थे कि दूसरों की रुचि हो सके; यह साबित करने की ritual नहीं कि आज आप काम पर आए हैं, न ही दिखावा
      इस system में design, experts के creative group के साथ मिलकर काम करने से उभरने वाली property है। यह design docs को exclude नहीं करता और architecture discussions अब भी शामिल रहती हैं, लेकिन explicit PRD/design doc process की मांग नहीं करता
      ऐसी जगह फिर से काम करना चाहूँगा। Google बिल्कुल उल्टा था और हर चीज में बहुत ज्यादा समय लगता था
    • इसलिए Google products बना ही नहीं पाता। कल मेरा नया Pixel 7 खराब हो गया
      इस तरह का नकली “हम बहुत smart हैं” वाला व्यवहार भी waste work का एक रूप है। company को वास्तव में काम करने वाले products पर focus करना चाहिए और उसी से खुद को judge करना चाहिए

  • एक और Googler हूँ
    Google के design docs बेकार हैं—इस पर पहले से कई अच्छे comments हैं, लेकिन मैं समस्या पर महसूस होने वाला एक और नज़रिया जोड़ना चाहता हूँ
    जैसा बताया गया है, design docs promotion material होते हैं, इसलिए वे बहुत ज्यादा फालतू भराव पैदा करते हैं। लेकिन वे असल documentation की जगह लेते हुए भी दिखते हैं
    हर design doc पूरा होते ही लगभग पुराना पड़ जाता है, लेकिन teams नए docs लिखने के बजाय उसी design doc की ओर इशारा करती हैं। नतीजतन Google की documentation काफी खराब और पुरानी है
    सच कहूँ तो “जो काम नहीं किया गया” उस पर 20 पन्ने लिखने के बजाय, जो चीज़ सच में मौजूद है उसे कैसे इस्तेमाल करें इस पर 2 पन्नों की usage guide लिखना अगर promotion material होता, तो कहीं बेहतर होता

  • क्या असली documents देखे जा सकते हैं? software design process documents सबसे सख्ती से रखे गए secrets जैसे लगते हैं। case study के लिए इस्तेमाल हो सकने वाला कोई असली document मैंने कभी नहीं देखा