GN⁺: 구글의 Design Docs 문서 작성 문화 (2020)
(industrialempathy.com)- Design docs는 Google의 소프트웨어 엔지니어링 문화의 핵심 요소 중 하나로, 소프트웨어 시스템이나 애플리케이션의 주요 저자가 코딩 프로젝트를 시작하기 전에 작성하는 비교적 비공식적인 문서임
- 고수준의 구현 전략과 주요 설계 결정을 문서화하며, 특히 그러한 결정 시 고려되었던 트레이드오프에 중점을 둠
- 소프트웨어 엔지니어의 직무는 코드를 작성하는 것이 아니라 문제를 해결하는 것이며, Design doc과 같은 비정형 텍스트가 프로젝트 초기 단계에서는 코드보다 더 간결하고 이해하기 쉬운 문제 해결 도구가 될 수 있음
Design docs의 소프트웨어 개발 라이프사이클에서의 역할
- 원래의 소프트웨어 설계 문서화 외에도 다음과 같은 기능을 수행함:
- 변경이 아직 저렴할 때 설계 이슈를 조기에 식별
- 조직 내에서 설계에 대한 합의 도출
- 횡단 관심사(cross-cutting concern) 고려 보장
- 시니어 엔지니어의 지식을 조직으로 전파
- 설계 결정에 대한 조직적 기억의 기반 형성
- 소프트웨어 설계자의 기술 포트폴리오에서 요약 아티팩트 역할
Design doc의 구조
- Design doc에는 엄격한 콘텐츠 가이드라인이 없는 비공식 문서이므로, 특정 프로젝트에 가장 적합한 형식으로 작성하는 것이 규칙임
- Context and scope: 새로운 시스템이 구축되는 배경과 실제로 구축되는 내용에 대한 개요 제공
- Goals and non-goals: 시스템의 목표와 목표가 아닌 것을 나열
- The actual design
- System-context-diagram: 시스템을 더 큰 기술 환경의 일부로 보여주는 다이어그램
- APIs: 시스템이 노출하는 API 스케치
- Data storage: 데이터를 저장/관리하는 방법 논의
- Code and pseudo-code: 새로운 알고리즘 설명 시에만 포함
- Degree of constraint: 솔루션 공간의 제약 정도가 설계 문서의 형태에 영향을 미치는 주요 요인 중 하나
- Alternatives considered: 유사한 결과를 합리적으로 달성할 수 있는 대안적 설계를 나열하고 각 설계의 트레이드오프와 주요 설계를 선택한 이유 설명
- Cross-cutting concerns: 보안, 프라이버시, 관찰 가능성 등 조직의 공통 관심사가 설계에 어떤 영향을 미치는지 설명
Design doc 작성 시기
- Design doc 작성 여부는 설계에 대한 조직적 합의, 문서화, 시니어 리뷰 등의 이점이 문서 작성에 따른 추가 작업보다 큰지에 달려 있음
- 문제의 복잡성이나 솔루션의 복잡성으로 인해 설계 문제에 대한 해결책이 모호한 경우가 아니라면 문서 작성의 가치는 적음
- 구현 매뉴얼에 가까운 Design doc은 불필요할 수 있음
- 프로토타이핑과 신속한 반복에는 Design doc 작성 오버헤드가 적합하지 않을 수 있음
Design doc의 라이프사이클
- Creation and rapid iteration: 문서 작성 및 동료와의 신속한 반복을 통해 안정적인 버전 도출
- Review: 더 넓은 청중과 공유되어 리뷰됨
- Implementation and iteration: 구현 중 설계 변경 사항 발생 시 문서 업데이트
- Maintenance and learning: 시스템을 이해하기 위한 가장 접근성 좋은 진입점 역할
GN⁺의 의견
- Design doc은 복잡한 소프트웨어 프로젝트의 가장 어려운 문제를 해결하는 데 있어 명확성을 얻고 합의를 도출하는 좋은 방법임. 사전 조사를 통해 불필요한 코딩을 피할 수 있어 비용을 절감해주지만, 동시에 작성과 검토에 시간이 소요되어 비용이 발생하기도 함
- 따라서 프로젝트에 맞게 Design doc 작성 여부를 현명하게 선택해야 함. 소프트웨어 설계에 대한 불확실성이 있고, 시니어 엔지니어의 조기 개입이 도움이 되며, 설계에 대한 조직적 합의가 필요하고, 팀이 보안 등 공통 관심사를 종종 간과하며, 레거시 시스템 설계에 대한 high-level 문서가 필요한 경우 Design doc 작성을 고려해 볼 만함
- 소프트웨어 설계 과정에서 문서화의 중요성을 잘 보여주는 사례로, 특히 대규모 팀에서 일관된 설계 문화를 확립하는 데 도움이 될 것으로 보임. 다만 문서화에 대한 부담으로 엔지니어들이 기피할 수 있는 만큼, 상황에 맞는 적절한 수준과 범위로 가이드라인을 마련하는 것이 중요해 보임
- 개인적으로는 1) 설계의 복잡성에 따른 트레이드오프 고려, 2) 구현 전 설계 이슈 조기 발견, 3) 신규 멤버의 빠른 학습을 위한 시스템 개요 제공 측면에서 Design doc의 유용성이 크다고 생각함. 단, 지나치게 형식적이거나 실제 구현과 동떨어진 문서가 되지 않도록 주의가 필요함
- 프로젝트 초기 혹은 복잡성이 높은 설계 단계에 국한해 Design doc을 의무화하되, 엔지니어가 자발적으로 작성할 수 있도록 인센티브를 제공하는 것도 방법이 될 수 있음. 문서 작성이 개별 엔지니어의 기술 포트폴리오 강화에도 도움이 된다는 점을 강조하면 좋겠음
Hacker News 의견
구글의 디자인 문서 문화에 대한 다양한 의견:
- 디자인 문서 작성이 승진을 위한 것이 되어버려서 실제 시스템을 만드는 사람들보다는 승진 위원회를 고려해 작성되는 경향이 있음
- 디자인 문서의 유형:
- 프로모션용 디자인 문서: 프로젝트의 목적보다는 프로젝트와 회사가 얼마나 대단한지 강조
- 터보 인캡슐레이터 디자인 문서: 이해하기 어려운 전문 용어로 가득함
- 신입 사원 디자인 문서: 내용은 없고 분량만 많음
- 근거 없는 사실로 가득한 디자인 문서: "모두가 아는" 사실을 근거로 들지만 실제로는 검증되지 않음
- 설계는 코딩 프로젝트의 일부이므로, 코딩 전에 문서로 모든 것을 계획하는 것은 잘못된 접근
- 사전 문서 작성은 사소한 지적을 할 구실을 줄 뿐이며, 중요한 문제는 미리 관련자들과 소통하며 해결하는 것이 나음
- 문서를 지속적으로 협업하며 업데이트 하는 것이 더 유용
- 디자인 문서에 허비되는 인력은 어마어마한 수준
- 아마존의 디자인 문서 문화는 훌륭했으나, 구글식 문화를 차용한 다른 회사에서는 무의미했음
- 승인 없이 프로젝트를 진행했음에도 뒤늦게 디자인 문서에 피드백을 주는 일이 있었음
- 디자인 문서가 실제 문서를 대체해버려서 오히려 문서화가 부실해지는 문제가 있음
- 디자인 문서의 장점도 있음: 생각을 정리하고, 결함을 발견하고, 의사소통을 원활히 하며, 작업량을 가늠할 수 있음