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

• Design docs, Google की software engineering संस्कृति के मुख्य तत्वों में से एक हैं। ये अपेक्षाकृत अनौपचारिक दस्तावेज़ होते हैं, जिन्हें किसी software system या application के मुख्य लेखक coding project शुरू करने से पहले लिखते हैं
  • ये high-level implementation strategy और प्रमुख design decisions को दस्तावेज़ित करते हैं, और खास तौर पर उन decisions के समय विचार किए गए trade-offs पर ज़ोर देते हैं
  • software engineer का काम सिर्फ code लिखना नहीं बल्कि समस्याएँ हल करना है, और Design doc जैसे unstructured text प्रोजेक्ट के शुरुआती चरण में code की तुलना में अधिक संक्षिप्त और समझने में आसान problem-solving tool हो सकते हैं

Software development lifecycle में Design docs की भूमिका

• मूल software design documentation के अलावा, ये निम्नलिखित भूमिकाएँ भी निभाते हैं:
  • बदलाव अभी कम लागत वाले हों तब design issues की शुरुआती पहचान
  • संगठन के भीतर design पर सहमति बनाना
  • cross-cutting concerns पर विचार सुनिश्चित करना
  • senior engineers के ज्ञान को संगठन में फैलाना
  • design decisions के लिए organizational memory की नींव बनाना
  • software designer के technical portfolio में summary artifact की भूमिका निभाना

Design doc की संरचना

• Design doc एक अनौपचारिक दस्तावेज़ है जिस पर सख्त content guidelines लागू नहीं होतीं, इसलिए नियम यह है कि इसे उसी रूप में लिखा जाए जो किसी खास project के लिए सबसे उपयुक्त हो
  • Context and scope: नया system किस पृष्ठभूमि में बनाया जा रहा है और वास्तव में क्या बनाया जा रहा है, इसका overview देता है
  • Goals and non-goals: system के goals और non-goals की सूची
  • The actual design
    • System-context-diagram: ऐसा diagram जो system को बड़े technical environment के एक हिस्से के रूप में दिखाता है
    • APIs: system द्वारा exposed APIs का sketch
    • Data storage: data को store/manage करने के तरीकों पर चर्चा
    • Code and pseudo-code: केवल तब शामिल किया जाता है जब किसी नए algorithm को समझाना हो
    • Degree of constraint: solution space पर constraints की मात्रा, design document के रूप को प्रभावित करने वाले प्रमुख कारकों में से एक है
  • Alternatives considered: ऐसे वैकल्पिक designs की सूची जो समान परिणाम को तर्कसंगत रूप से हासिल कर सकते हों, साथ ही प्रत्येक design के trade-offs और मुख्य design चुने जाने के कारण
  • Cross-cutting concerns: यह बताता है कि security, privacy, observability जैसे संगठन के common concerns design को कैसे प्रभावित करते हैं

Design doc कब लिखना चाहिए

• Design doc लिखना है या नहीं, यह इस बात पर निर्भर करता है कि organizational agreement, documentation, senior review जैसे लाभ दस्तावेज़ लिखने के अतिरिक्त काम से अधिक हैं या नहीं
  • यदि समस्या की जटिलता या solution की जटिलता के कारण design issue का समाधान अस्पष्ट न हो, तो दस्तावेज़ लिखने का मूल्य कम होता है
  • implementation manual के क़रीब पहुँचने वाला Design doc अनावश्यक हो सकता है
  • prototyping और तेज़ iteration के लिए Design doc लिखने का overhead उपयुक्त नहीं हो सकता

Design doc का lifecycle

1. Creation and rapid iteration: दस्तावेज़ लिखना और साथियों के साथ तेज़ी से iteration करके एक स्थिर version तक पहुँचना
2. Review: इसे व्यापक audience के साथ साझा किया जाता है और review किया जाता है
3. Implementation and iteration: implementation के दौरान design में बदलाव होने पर दस्तावेज़ अपडेट किया जाता है
4. Maintenance and learning: system को समझने के लिए सबसे सुलभ entry point की भूमिका निभाना

GN⁺ की राय

• Design doc, जटिल software projects की सबसे कठिन समस्याओं को हल करने में clarity पाने और consensus बनाने का अच्छा तरीका है। पहले से जाँच-पड़ताल करके अनावश्यक coding से बचा जा सकता है, जिससे लागत घटती है, लेकिन साथ ही इसे लिखने और review करने में समय लगता है, इसलिए इसकी भी एक लागत होती है
• इसलिए project के अनुसार Design doc लिखना है या नहीं, यह समझदारी से तय करना चाहिए। यदि software design को लेकर अनिश्चितता हो, senior engineer की शुरुआती भागीदारी मददगार हो, design पर organizational agreement की ज़रूरत हो, team अक्सर security जैसे common concerns को नज़रअंदाज़ करती हो, और legacy system design पर high-level दस्तावेज़ चाहिए हों, तो Design doc लिखने पर विचार किया जा सकता है
• यह software design process में documentation के महत्व को अच्छी तरह दिखाने वाला उदाहरण है, और विशेष रूप से बड़े teams में एक सुसंगत design culture स्थापित करने में मददगार लग सकता है। हालांकि documentation के बोझ के कारण engineers इससे बचना चाह सकते हैं, इसलिए स्थिति के अनुसार उचित स्तर और दायरे की guidelines बनाना महत्वपूर्ण लगता है
• व्यक्तिगत रूप से, मुझे लगता है कि 1) design की जटिलता के अनुसार trade-offs पर विचार, 2) implementation से पहले design issues की शुरुआती पहचान, 3) नए members की तेज़ learning के लिए system overview देने—इन तीनों पहलुओं में Design doc बहुत उपयोगी है। हालांकि, यह ध्यान रखना ज़रूरी है कि दस्तावेज़ अत्यधिक औपचारिक या वास्तविक implementation से कटा हुआ न बन जाए
• project के शुरुआती चरण या अधिक जटिल design चरणों तक Design doc को अनिवार्य किया जा सकता है, और साथ ही engineers को इसे स्वेच्छा से लिखने के लिए incentive भी दिया जा सकता है। यह बात ज़ोर देकर कही जा सकती है कि दस्तावेज़-लेखन व्यक्तिगत engineer के technical portfolio को मजबूत करने में भी मदद करता है

[GN⁺]

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

Google की design docs संस्कृति पर विभिन्न राय:

• design docs लिखना प्रमोशन के लिए होने लगा है, इसलिए इन्हें असली सिस्टम बनाने वाले लोगों से ज़्यादा promotion committee को ध्यान में रखकर लिखे जाने की प्रवृत्ति है
• design docs के प्रकार:
  • प्रमोशन-उन्मुख design doc: प्रोजेक्ट के उद्देश्य से ज़्यादा इस बात पर ज़ोर कि प्रोजेक्ट और कंपनी कितने महान हैं
  • turbo encapsulator design doc: समझने में कठिन jargon से भरा हुआ
  • नए कर्मचारी का design doc: सामग्री कम, लंबाई ज़्यादा
  • बिना आधार वाले तथ्यों से भरा design doc: "सबको पता है" जैसे दावों को आधार बनाता है, लेकिन वे वास्तव में सत्यापित नहीं होते
• design coding project का हिस्सा है, इसलिए coding से पहले हर चीज़ को document में पूरी तरह plan करना गलत तरीका है
• पहले से document लिखना अक्सर केवल छोटी-मोटी आलोचना का बहाना देता है; अहम मुद्दों को पहले से संबंधित लोगों से बात करके सुलझाना बेहतर है
• दस्तावेज़ को लगातार सहयोग के साथ update करना ज़्यादा उपयोगी है
• design docs पर बर्बाद होने वाली मानव-शक्ति का स्तर बहुत बड़ा है
• Amazon की design docs संस्कृति शानदार थी, लेकिन Google-शैली की संस्कृति अपनाने वाली दूसरी कंपनियों में यह निरर्थक रही
• बिना approval के project आगे बढ़ाने के बावजूद, बाद में design doc पर feedback दिया गया
• design docs ने असली documentation की जगह ले ली है, जिससे उल्टा documentation कमज़ोर हो जाता है
• design docs के फायदे भी हैं: सोच को व्यवस्थित करना, खामियाँ ढूँढना, communication को सुचारु बनाना, और काम की मात्रा का अंदाज़ा लगाना