구글의 Design Docs 문서 작성 문화 (2020)

 (industrialempathy.com)
4P by GN⁺ | ★ favorite | 댓글 1개
  • Google에서 Design Doc은 코딩 전에 문제의 맥락, 고수준 구현 전략, 핵심 설계 결정을 정리해 설계 비용이 낮을 때 위험을 줄이는 문서임
  • 문서의 가치는 완성된 코드 설명보다 트레이드오프와 대안을 드러내 조직이 같은 판단 근거를 공유하게 하는 데 있음
  • 좋은 Design Doc은 맥락과 범위, 목표와 비목표, 실제 설계, 고려한 대안, 보안·개인정보·관측 가능성 같은 횡단 관심사를 프로젝트에 맞게 담음
  • 설계가 이미 명확하거나 문서가 구현 절차만 나열한다면 Design Doc의 작성·리뷰 오버헤드가 이점보다 커질 수 있음
  • 문서는 작성, 리뷰, 구현 중 갱신, 유지보수와 학습으로 이어지며, 출시 전 설계가 바뀌면 문서도 함께 업데이트하는 편이 좋음

Design Doc이 맡는 역할

  • Google에서 Design Doc은 소프트웨어 시스템이나 애플리케이션의 주요 작성자가 코딩 프로젝트를 시작하기 전에 만드는 비교적 비공식 문서임
  • 고수준 구현 전략과 핵심 설계 결정을 담되, 단순한 결정 목록보다 왜 그런 선택을 했는지 보여주는 트레이드오프가 중요함
  • 소프트웨어 엔지니어링의 목적은 코드 생산 자체가 아니라 문제 해결이므로, 프로젝트 초반에는 비정형 텍스트가 코드보다 더 간결하고 이해하기 쉬울 수 있음
  • Design Doc은 개발 생명주기에서 여러 역할을 함
    • 변경 비용이 낮을 때 설계 이슈를 일찍 발견함
    • 조직 안에서 설계 합의를 형성함
    • 보안, 개인정보, 관측 가능성 같은 횡단 관심사를 놓치지 않게 함
    • 시니어 엔지니어의 지식을 조직 안으로 확장함
    • 설계 결정에 대한 조직의 기억을 남김
    • 설계자의 기술 포트폴리오를 요약하는 산출물이 됨

Design Doc의 기본 구성

  • Design Doc에는 엄격한 템플릿이 없으며, 첫 번째 원칙은 특정 프로젝트에 가장 적합한 형식을 고르는 것임
  • 다만 자주 유용한 구조는 맥락과 범위, 목표와 비목표, 실제 설계, 고려한 대안, 횡단 관심사, 적절한 길이로 정리할 수 있음

  • 맥락과 범위

    • 새 시스템이 놓일 환경과 실제로 무엇을 만들지에 대한 거친 개요를 제공함
    • 요구사항 문서가 아니므로 간결해야 하며, 독자가 빠르게 배경을 따라잡게 하는 데 초점을 둠
    • 일부 사전 지식은 가정할 수 있고, 세부 정보는 링크로 연결할 수 있음
    • 이 섹션은 객관적 배경 사실에 집중해야 함

  • 목표와 비목표

    • 시스템의 목표와, 때로는 더 중요한 비목표를 짧은 불릿 목록으로 정리함
    • 비목표는 “시스템이 크래시하면 안 됨”처럼 목표의 단순 부정이 아니라, 목표가 될 수도 있었지만 명시적으로 제외한 항목임
    • 데이터베이스 설계에서 ACID 준수는 목표인지 비목표인지 알아야 하는 좋은 예임
    • 비목표라 해도 목표 달성을 방해하는 트레이드오프가 없다면 해당 속성을 제공하는 솔루션을 선택할 수 있음

실제 설계를 쓰는 방식

  • 실제 설계 섹션은 개요에서 시작해 세부 사항으로 내려가야 함
  • Design Doc은 소프트웨어 설계에서 발생한 트레이드오프를 기록하는 장소임
  • 맥락이라는 사실, 목표와 비목표라는 요구사항을 바탕으로 해법을 제안하고, 특정 해법이 목표를 가장 잘 만족하는 이유를 보여줘야 함
  • 문서 형식의 장점은 문제 집합에 맞는 표현 방식을 유연하게 선택할 수 있다는 데 있음

  • 시스템 컨텍스트 다이어그램

    • 많은 문서에서 system-context-diagram이 유용할 수 있음
    • 이 다이어그램은 시스템을 더 큰 기술 환경의 일부로 보여주며, 독자가 이미 아는 환경 안에서 새 설계를 이해하게 함

  • API와 데이터 저장

    • 설계 대상 시스템이 API를 노출한다면 API를 스케치하는 것이 대체로 좋음
    • 형식적인 인터페이스나 데이터 정의를 그대로 복사해 붙여넣는 방식은 피해야 함
    • 이런 정의는 장황해지기 쉽고 불필요한 세부 사항을 포함하며 빠르게 낡을 수 있음
    • 설계와 트레이드오프에 관련된 부분에 집중해야 함
    • 데이터를 저장하는 시스템은 데이터가 어떻게, 어떤 대략적 형태로 저장되는지 다뤄야 함
    • 전체 스키마 정의를 붙여넣기보다 설계 판단과 관련된 부분을 설명하는 편이 좋음

  • 코드와 의사코드

    • Design Doc에는 코드를 거의 넣지 않는 편이 좋음
    • 새로운 알고리듬을 설명하는 경우를 제외하면 의사코드도 드물게 사용해야 함
    • 설계가 구현 가능하다는 점을 보여주는 프로토타입이 있다면 적절히 링크할 수 있음

제약 정도가 문서 형태를 바꿈

  • 소프트웨어 설계와 Design Doc의 형태에 영향을 주는 주요 요인 중 하나는 해법 공간의 제약 정도임
  • 한쪽 끝에는 목표만 있고 해법은 무엇이든 가능한 그린필드 소프트웨어 프로젝트가 있음
    • 이런 문서는 넓은 범위를 다룰 수 있지만, 관리 가능한 해법 집합으로 좁혀가기 위한 규칙을 빠르게 정의해야 함
  • 다른 한쪽 끝에는 가능한 해법은 잘 정의되어 있지만, 그 해법들을 어떻게 조합해 목표를 달성할지 명확하지 않은 시스템이 있음
    • 변경하기 어려운 레거시 시스템일 수 있음
    • 호스트 프로그래밍 언어의 제약 안에서 동작해야 하는 라이브러리 설계일 수 있음
  • 이런 경우 비교적 쉽게 할 수 있는 작업을 나열할 수는 있지만, 목표 달성을 위해 이를 창의적으로 조합해야 함
  • 여러 해법이 모두 완벽하지 않다면, 문서는 식별된 트레이드오프를 바탕으로 최선의 방식을 고르는 데 집중해야 함

대안과 횡단 관심사

  • 고려한 대안

    • 이 섹션은 비슷한 결과를 합리적으로 달성할 수 있었던 대안 설계를 나열함
    • 각 설계가 만드는 트레이드오프와, 그 트레이드오프가 최종 선택으로 어떻게 이어졌는지에 초점을 둬야 함
    • 선택되지 않은 해법은 간결하게 다뤄도 되지만, 이 섹션은 문서에서 매우 중요함
    • 독자가 궁금해할 수 있는 다른 해법들이 프로젝트 목표에 비춰 왜 덜 바람직한지 보여줘야 함

  • 횡단 관심사

    • 조직은 이 섹션을 통해 보안, 개인정보, 관측 가능성 같은 횡단 관심사가 항상 고려되도록 할 수 있음
    • 보통 각 관심사가 설계에 어떤 영향을 주고 어떻게 처리되는지 설명하는 짧은 섹션이 됨
    • 팀은 자신들의 상황에서 어떤 관심사를 표준으로 삼을지 정해야 함
    • Google 프로젝트는 중요성 때문에 별도의 개인정보 Design Doc을 요구하며, 개인정보와 보안에 대한 전용 리뷰가 있음
    • 리뷰 완료는 프로젝트 출시 시점까지 요구됨
    • 설계가 처음부터 이를 반영하도록 개인정보·보안 팀과 가능한 한 일찍 협업하는 것이 모범 사례임
    • 해당 주제의 전용 문서가 있다면 중앙 Design Doc은 상세 내용을 반복하지 않고 참조할 수 있음

길이와 작성하지 않아도 되는 경우

  • 적절한 길이

    • Design Doc은 충분히 상세해야 하지만 바쁜 사람들이 실제로 읽을 수 있을 만큼 짧아야 함
    • 큰 프로젝트에서는 약 10~20페이지가 적절한 지점으로 보임
    • 그보다 훨씬 길어진다면 문제를 더 관리 가능한 하위 문제로 나누는 편이 나을 수 있음
    • 1~3페이지짜리 미니 Design Doc도 가능함
    • 점진적 개선이나 애자일 프로젝트의 하위 작업에 특히 유용함
    • 긴 문서와 같은 단계를 수행하되, 더 간결하고 제한된 문제 집합에 집중함

  • 작성하지 않아도 되는 경우

    • Design Doc 작성에는 오버헤드가 있음
    • 작성 여부는 설계 합의, 문서화, 시니어 리뷰 등의 이점이 문서 생성 비용을 넘어서는지에 달려 있음
    • 핵심 판단 기준은 설계 문제가 모호한지 여부임
    • 문제 복잡성, 해법 복잡성, 또는 둘 다 때문에 모호할 수 있음
    • 모호하지 않다면 문서 작성 과정의 가치는 작음
    • 문서가 사실상 구현 매뉴얼이라면 Design Doc이 필요하지 않을 수 있음
    • “이렇게 구현하겠다”만 말하고 트레이드오프, 대안, 의사결정 설명이 없다면 바로 프로그램을 작성하는 편이 나았을 수 있음
    • 해법이 너무 명확해서 트레이드오프가 없다면 문서의 가치가 낮음
    • Design Doc의 작성과 리뷰 오버헤드는 프로토타이핑과 빠른 반복에 맞지 않을 수 있음
    • 애자일 방법론을 따른다고 해서 알려진 문제의 해법을 제대로 고민하지 않아도 되는 것은 아님
    • 프로토타이핑 자체가 Design Doc 작성의 일부가 될 수 있으며, “해봤고 동작한다”는 설계 선택의 강한 근거가 될 수 있음

Design Doc의 생명주기

  • Design Doc의 생명주기는 네 단계로 구성됨
    1. 작성과 빠른 반복
    2. 리뷰
    3. 구현과 반복
    4. 유지보수와 학습

  • 작성과 빠른 반복

    • 문서는 작성자가 단독으로 쓰거나 공동 작성자들과 함께 작성함
    • 이후 문제 공간을 가장 잘 아는 동료들과 공유하며 빠르게 반복함
    • 동료들의 명확화 질문과 제안이 문서를 비교적 안정적인 첫 버전으로 이끎
    • Google에는 버전 관리와 코드 리뷰 도구로 문서 만들기를 선호하는 엔지니어와 팀도 있지만, 대다수 Design Doc은 Google Docs에서 작성되고 협업 기능을 많이 사용함

  • 리뷰

    • 리뷰 단계에서는 원래 작성자와 가까운 협업자보다 더 넓은 독자에게 문서를 공유함
    • 리뷰는 큰 가치를 더할 수 있지만 오버헤드의 함정이 될 수 있으므로 신중하게 다뤄야 함
    • 가벼운 방식은 문서를 더 넓은 팀 메일링 리스트에 보내 사람들이 살펴볼 기회를 주는 것임
    • 논의는 주로 문서의 댓글 스레드에서 이뤄짐
    • 무거운 방식은 작성자가 문서를 시니어 엔지니어 독자 앞에서 발표하는 정식 설계 리뷰 회의임
    • Google의 많은 팀은 이런 리뷰를 위한 정기 회의를 갖고 있음
    • 이런 회의를 기다리면 개발 프로세스가 크게 느려질 수 있음
    • 가장 중요한 피드백을 직접 구하고 더 넓은 리뷰를 진행의 차단 요소로 만들지 않는 방식으로 완화할 수 있음
    • Google이 더 작은 회사였을 때는 설계를 하나의 중앙 메일링 리스트로 보내고 시니어 엔지니어들이 여유가 있을 때 리뷰하는 방식이 관례였음
    • 이 방식은 회사 전체에 비교적 균일한 소프트웨어 설계 문화를 만드는 장점이 있었음
    • 엔지니어링 조직이 훨씬 커지면서 중앙집중식 접근을 유지하기 어려워짐
    • 리뷰의 주요 가치는 조직의 결합된 경험이 설계에 반영될 기회를 만드는 데 있음
    • 특히 관측 가능성, 보안, 개인정보 같은 횡단 관심사를 설계가 고려하도록 하는 데 리뷰 단계가 일관되게 도움을 줌
    • 리뷰의 핵심 가치는 이슈 발견 자체보다, 변경 비용이 낮은 개발 생명주기 초기에 이슈가 발견되는 데 있음

  • 구현과 반복

    • 추가 리뷰가 설계에 큰 변경을 요구할 가능성이 낮다는 확신이 생기면 구현을 시작할 때임
    • 계획이 현실과 부딪히면 결함, 처리되지 않은 요구사항, 틀린 것으로 드러난 추정이 나타나고 설계 변경이 필요해질 수 있음
    • 이 경우 Design Doc을 업데이트하는 것이 강하게 권장됨
    • 경험칙으로, 설계한 시스템이 아직 출시되지 않았다면 반드시 문서를 업데이트해야 함
    • 실제로는 사람들이 문서를 잘 업데이트하지 못하고, 다른 실무적 이유로 변경 사항이 새 문서로 분리되는 일이 많음
    • 그 결과 하나의 일관된 문서라기보다 수정 조항이 붙은 미국 헌법 같은 상태가 될 수 있음
    • 원래 문서에서 이런 수정 문서로 링크를 걸어두면, 나중에 유지보수 프로그래머가 Design Doc 고고학으로 대상 시스템을 이해하는 데 큰 도움이 됨

  • 유지보수와 학습

    • Google 엔지니어가 처음 만지는 시스템을 접하면 자주 묻는 첫 질문은 “Design Doc이 어디 있나?”임
    • Design Doc도 다른 문서처럼 시간이 지나면 현실과 어긋나는 경향이 있지만, 시스템을 만든 사고 과정을 배우는 가장 접근하기 쉬운 진입점이 되는 경우가 많음
    • 작성자는 1~2년 뒤 자신의 Design Doc을 다시 읽어보는 것이 좋음
    • 무엇을 맞혔는지 확인함
    • 무엇을 틀렸는지 확인함
    • 오늘이라면 무엇을 다르게 결정할지 생각함
    • 이런 질문에 답하는 과정은 엔지니어로 성장하고 시간이 지나며 소프트웨어 설계 역량을 개선하는 데 도움이 됨

언제 Design Doc으로 시작할지 판단하기

  • Design Doc은 소프트웨어 프로젝트의 어려운 문제를 해결할 때 명확성을 얻고 합의를 형성하는 좋은 방법임
  • 사전 조사로 피할 수 있었던 코딩의 막다른 길을 줄여 비용을 절약할 수 있음
  • 동시에 작성과 리뷰에 시간이 들기 때문에 비용도 발생함
  • 다음 질문을 고려할 수 있음
    • 올바른 소프트웨어 설계가 불확실하고, 확신을 얻기 위해 사전에 시간을 쓰는 것이 타당한가?
    • 모든 코드 변경을 리뷰하지 못할 수 있는 시니어 엔지니어를 설계 단계에 참여시키는 것이 도움이 되는가?
    • 소프트웨어 설계가 모호하거나 논쟁적이어서 조직적 합의가 가치 있는가?
    • 팀이 개인정보, 보안, 로깅 또는 다른 횡단 관심사를 설계에서 가끔 잊는가?
    • 조직 안의 레거시 시스템 설계에 대한 고수준 통찰을 제공하는 문서가 강하게 필요한가?
  • 이 질문 중 3개 이상에 “예”라고 답한다면, Design Doc은 다음 소프트웨어 프로젝트를 시작하는 데 좋은 방법일 가능성이 높음

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견들

  • Google의 설계 문서 문화 때문에 회사를 떠났음
    입사 직후 다른 제품 영역에서 여러 번 해본 비교적 사소한 작업을 아주 높은 수준으로 정리한 문서를 썼는데, 동료가 따로 불러 “여기서는 이렇게 하지 않는다”고 말함
    내가 제시한 방식은 권장 방식의 작은 변형에 불과했지만, “이 일을 해내는 더 많은 방법을 평가하라”고 했고, 이유를 묻자 “폭넓게 고려했다는 걸 보여준다”고 답함
    Google에는 가짜 일이 분명히 존재하며, 다른 팀에 들어갔더라면 싶음

    • 보상하는 행동이 실제 행동이 됨. 초창기 설계 문서는 방향에 합의하고 동료에게 맥락을 제공하는 도구였지만, 이후 인원이 기하급수적으로 늘면서 선의의 관리자들이 성과 평가를 위해 문서를 쓰라고 했고 상황이 꼬이기 시작함
      Google 문화는 스스로를 흉내 내는 화물 숭배가 되어버림
      Google 이후 다닌 몇몇 회사는 승진 절차를 자세히 논의하기를 꺼렸는데, 사람들이 그 절차에 맞춰 미세 최적화하면 무슨 일이 벌어지는지 봤기 때문임
    • 오래되고 성숙한 제품을 맡은 팀들이 만든 문화 때문일 가능성이 큼. 그런 곳에서는 사소한 프로젝트를 출시하는 데도 최소 10명, 내 경우 보통 20~30명과 협업하고 영향 범위는 100~500명까지 감
      모두 바쁘기 때문에 전원과 가볍게 1:1로 이야기할 수 없고, 이해관계자 검토를 제대로 못 받으면 화난 사람들이 찾아와 출시를 롤백하게 만들 가능성이 큼
      이런 맥락에서 설계 문서는 정보량이 많은 주제를 위한 비동기 커뮤니케이션 도구임. 제품이 성공하면 10년 뒤 합류한 사람들과도 이 문서를 통해 대화하게 됨
      지금도 발목 잡는 이상한 결정을 설명해 주는 2010년의 무작위 설계 문서 덕분에 여러 번 구원받았음. 날렵한 소규모 팀이나 덜 복잡한 작업에는 잘 맞지 않을 수 있지만, 엔지니어링 문화에는 화물 숭배가 되었더라도 대체로 나름의 이유와 맥락이 있음
    • 단순하고 명확한 방법이 사실상 하나뿐이면 1페이지 문서를 쓰지만, 이 부분은 Google 편을 들고 싶음
      무언가를 설계하는데 고려 중인 해법이 하나뿐이라면 설계가 없거나 충분히 철저하지 않은 것임. 선택지와 절충이 설계를 만드는 요소임
    • 내가 일하는 곳에는 반대 문제가 있음. 비교적 사소한 작업에 대해 아주 높은 수준의 설계 문서를 써 달라고 하면 “할 방법이 여러 가지라 이런 문서는 쓸모없고, 작업이 사소하니 엔지니어가 그중 하나를 골라 하면 된다”고 함
      이런 사람들 중 다수는 회사와 15년 넘게 일한 외부 컨설턴트라, 같은 사람들이 같은 작업을 해온 덕분에 이미 어느 정도 표준은 있음. 그런데도 “사람들이 표준을 따르지 않으면 어떻게 되나”라는 허수아비를 만들려고 애씀
      결과적으로 설계 문서가 없거나 심하게 낡아 있고, 회사는 해마다 같은 컨설턴트를 부풀려진 비용으로 계속 고용하게 됨
    • 다른 팀에 있을 때는 그렇게 느꼈음. 문서를 쓰기 위해 문서를 쓰는 것처럼 기대받는 느낌, 즉 화물 숭배식 엔지니어링에 가까웠음
      지금은 근속 15년 이상의 오래된 Googler가 많은 팀에 있는데, 설계 문서는 필요할 때만 존재함. 여러 시스템에 걸치거나, 절충이 많아 명백히 복잡한 경우 등임. 그 외에는 그냥 “CLS를 작성하라”는 식임

  • Google에서 설계 문서는 승진 패킷에 들어가는 핵심 자료라 문제가 생기는 듯함
    그래서 문서가 원래 독자인 해당 시스템 작업자보다 승진 위원회를 더 의식해 작성됨

    • 지금까지 다닌 모든 회사에서 그랬음. 경력은 평판이나 능력보다 노출도에 더 좌우됨. 설계 문서는 윗사람들에게 매우 잘 보임
      새 회사에 들어갈 때마다 설계 문서를 쓰기 시작하자고 제안하는데, 그러면 즉시 경영진에게 좋은 인상을 줌 :)
    • 그 때문에 필요도 없는데 많은 문서가 더 복잡한 설계 형식을 따르게 됨. 문서를 훑어볼 시간밖에 없는 사람들에게 성과 점수를 더 받으려는 목적임
      내가 읽은 많은 문서는 이미 원하는 결정을 정해 놓고, 문서 시작 시점에는 그 결정을 보여주기 위해 꾸며낸 선택지 2개 이상을 붙인 것처럼 보였음. 하나는 너무 단순하고 하나는 불필요한 과잉 설계인 식으로 대비시킨 뒤, 합리적으로 보이는 안을 고름
    • 개발자들은 설계 문서를 승진 위원회를 위해 쓴다고 대놓고 말함. 그게 목표이고 나머지는 부차적임
      어떤 설계 문서를 승진 패킷에 쓸지 모르기 때문에 아무리 작은 일도 모두 설계 문서로 남김. 1페이지 설계 문서라는 개념은 있지만 보통 한 페이지에서 여러 페이지로 커짐
      1주짜리 프로젝트에도 설계 문서가 쓰이고, 다른 회사라면 JIRA 티켓 하나로 끝났을 20, 30, 40쪽짜리 설계 문서를 검토해야 했던 적도 있음
      많은 사람이 승진 위원회가 “작성자 혼자 쓴 문서”를 보고 싶어 한다고 배웠고, 그것이 맞든 아니든 이 믿음은 모든 것을 더 느리게 만들고 교차 학습을 억제함. 한 분기 이상 고립되어 설계 문서만 쓰는 소프트웨어 엔지니어도 봤음
      설계 문서에서 실제 설계가 핵심이어야 하지만, 나머지 99%는 문제 정의임. 리뷰 중 문제 정의를 개선하다가 설계를 폐기하고 문서 대부분을 다시 써야 했던 적이 너무 많음
      최악은 문제 정의를 개선하자 복잡한 설계가 필요 없는 단순한 해법이 드러나는 경우임. 작성자는 복잡한 설계에 많은 시간을 투자했고, 역사적으로도 많은 위원회가 그런 복잡성을 승진 근거로 봤기 때문에 단순한 해법에 저항함
      설계 문서에 대안이 전혀 없는 경우도 봤음. 그냥 해야 할 일이나 누군가 하고 싶은 일을 노동집약적으로 적어둔 것뿐이었음
      이러다 보면 설계 문서가 흐릿하게 보면 버그 추적 시스템처럼 변함. 모두 자기 설계 문서를 작업 중이고 버그는 작업하지 않음. 버그로는 승진할 수 없기 때문임
      새 팀에 들어가면 설계 문서만 보면 된다는 식으로 말하지만, 실제로는 중앙에서 추적되지 않는 경우가 많음. 많은 팀에서 설계 문서는 팀이나 프로젝트 소유가 아니라 개인 소유인데, 다른 사람이 기여하지 않았다는 걸 보장할 수 있기 때문이고 이것 역시 승진 위원회 때문임
      접근 권한이 없는 설계 문서도 많은데, 극비라서가 아니라 그냥 그렇게 되어 있음. 팀에 설계 문서가 두세 개 있는 것도 아니고 읽어야 할 산더미가 있음. Google의 이직 주기가 약 2년인 상황에서는 많은 문서가 시간 속에 사라짐
      다른 회사라면 새 팀에 들어온 사람에게 “필요한 건 닫힌 버그를 전부 읽거나 주 브랜치의 모든 커밋 메시지를 읽으면 된다”고 말하는 것과 비슷함
      다른 곳이었다면 점심 후 붙잡혀 팀과 화이트보드 앞에서 몇 시간 동안 문제를 정의했을 것임. 선임들이 후배에게 이런 문제를 어떻게 생각해야 하는지 실시간으로 가르치고 빠르게 반복했을 것임
      대부분은 버그 추적 시스템에 적거나, 큰 일이라면 프로젝트 위키나 폴더에 적어 모두의 소유로 만들었을 것임
      위의 문제들은 모두 개선 가능하고 실제로 개선하려 해봤지만, 문화는 천천히 바뀜. 설계 문서라는 개념 자체는 좋지만 함정이 있고, Google의 많은 사람이 쓰는 방식은 그 답이 아님
    • 그뿐 아니라 관료적 요구사항을 충족하기 위해서이기도 함. 다른 사람 문서에 댓글을 달아 리더십을 보여주기도 하고
      비용보다 가치가 큰 설계 문서가 그립다
    • 차이가 뭔지 잘 모르겠음. 팀원이 필요로 하는 것보다 더 많은 맥락을 주거나 문제를 실제보다 복잡하게 보이게 하는 정도 아닐까 함
      대체로 그 전략이 효과를 내는 건 못 봤음
      반면 맥락 제공용으로, 팀이 무엇을 했고 하고 있으며 문제가 무엇인지 등을 정리한 긴 문서는 있었고 그런 것들은 길고 과장되는 경향이 있었음

  • 언급된 회사에서 일하고 있지만 글쓴이와 같은 경험은 아님
    설계 문서에는 여러 유형이 있는데, 그중 유용한 것은 없었음. Google에서 유용한 설계 문서를 본 적은 드뭄. 설계 문서는 절차 지향이 과한 엔지니어를 위한 것처럼 느껴짐
    내가 본 유형은 대략 이렇음: 승진용 설계 문서는 무엇을 해결하려는지 설명하지 않고 이 프로젝트가 얼마나 훌륭하고 회사를 더 좋게 만드는지만 말함. 논리적 결론은 작성자가 승진해야 한다는 것임
    터보 인캡슐레이터 설계 문서는 처음 보는 용어로 가득한 기술 잡담 문서라 팀의 선임이 아니면 이해할 수 없음. 가끔은 선임들도 이해하는지 확신이 안 듦
    신입 졸업생 설계 문서는 내용은 없지만 대학을 막 졸업한 사람이 무엇을 증명하려는지 최대한 길게 만든 문서임. 정보를 전달하지 않고, 이미 작성한 코드를 크게 복붙해 70쪽가량을 채운 경우가 많음
    꾸며낸 사실 설계 문서는 “모두가 안다”, “다들 그렇게 말한다”로 가득함. 정치인처럼 노골적이진 않지만 “이건 좋은 관행을 따른다”, “이 소프트웨어는 느리다, 그러므로…” 같은 식으로 자기 설계를 밀어붙임. 누가 좋은 관행을 정의했는지, 왜 좋은 관행인지, 무엇이 느린지, 측정했는지, 최종 사용자 느낌인지가 빠져 있음
    내가 본 설계 문서의 99%가 이랬음. 예외는 있지만 경험상 매우 드뭄. 글쓴이가 이 관행을 밀어붙이는 게 놀라움. 다만 엔지니어가 아니라 디렉터였으니 그 자리에서는 설계 문서가 말이 될지도 모르겠고, 여전히 그런 사람들이 어떤 가치를 주는지는 모르겠음
    [1] https://en.wikipedia.org/wiki/Turbo_encabulator

    • 그건 바뀐 것 같음. 2006~2014년에 그곳에서 일했는데 당시 대부분의 설계 문서는 유용했고, 글에서 설명한 기본 구조를 따랐음. 시스템 맥락 다이어그램은 없었지만
      초기에 눈에 띈 점은 Google Docs에 유지되는 설계 문서가 버전 관리 저장소에 있는 것보다 품질이 낮은 경향이 있었다는 것임. 그게 작성 시기의 대리 지표였는지, 코드 리뷰 과정이 Docs 편집보다 더 엄격해서였는지는 모르겠음
      내가 큰 설계 문서, 아마 40쪽 정도를 썼을 때는 관례대로 손으로 쓴 HTML로 작성하고 코드 리뷰 시스템을 통해 진행했음. 중앙 메일링 리스트와 웹 서버에도 올렸고, 3번 직원에게 피드백을 받은 것도 좋았음. 중앙 위치에 카테고리별로 정렬되어 있어 찾기 쉬웠음
      당시 설계 문서 하나만으로 승진에 중요할 만큼 큰 비중을 차지했다고는 기억하지 않음. 승진은 특정 산출물이 아니라 전체 영향력에 관한 것이어야 했음. 물론 시스템에는 큰 결함이 있었고 나쁜 의미로 놀라운 결정도 자주 나왔지만, 그때는 성과 평가에 최적화된 설계 문서를 읽은 기억이 없음
      초기의 손으로 쓴 HTML 설계 문서가 모여 있는 웹사이트를 찾을 수 있다면 훑어보길 권함. 당시 시스템이 현역이었을 때라면 더 유용하게 느꼈을 수도 있음
      SmartASS 같은 오래된 문서 중 일부는 기반 방정식과 모델에 대한 자세한 설명으로 가득했고, 작동 방식과 왜 그런 접근을 골랐는지 이해하는 데 큰 도움이 되었음. 나중에 내 설계 작업에도 영향을 줬음. 나는 디렉터가 아니라 그냥 엔지니어였고, 실제로 도움이 됐음
      chromium.org 웹사이트에 연결된 Chrome 설계 문서 중에도 과거에 구조를 이해하는 데 도움이 된 것들이 있음
    • 선임에 비해 주니어 역할이 비교적 많은 경우에는 설계 문서가 잘 작동하는 걸 봤음
      주니어 개발자가 해법을 미리 생각하고 결정을 정당화하게 만들며, 선임 개발자가 그 결정을 검증하고 비동기 피드백을 줄 수 있게 해줌
      다만 나는 항상 스타트업에서 일해서 30~40명 넘는 엔지니어 조직에서는 일해본 적이 없음. 빅테크는 다르겠지만 내 경험은 긍정적이었음
    • 하나 빠뜨린 듯함. 제발 코딩 좀 시작하게 해줘 문서가 있음
    • 기술 문서, 설계 문서든 더 짧은 문서든 용도는 단순하다고 봄. 프로젝트의 모든 세부사항을 한 번에 머릿속에 담을 수 없는 지점에 도달하면 문서를 써야 함
      마찬가지로 다른 엔지니어에게 설명하는 데 오래 걸린다면, 최소 30분 정도라도, 시간을 아끼기 위해 문서를 써야 함
      어떻게 문서를 전혀 쓸 필요가 없다고 생각할 수 있는지 모르겠음
    • 두 번째 유형은 “내가 무엇을 하고 있고 이 문제를 어떻게 풀고 있는지 팀이나 기술 리더와 소통해야 한다”는 의미였던 경험이 있음
      나중에 승진을 준비할 때는 2번 범주의 문서에 맥락을 충분히 더해 1번 범주로 만들게 됨

  • 문서화는 일반적으로 좋지만, 이 접근은 결함이 있어 보임
    “코딩 프로젝트에 착수하기 전에” 소프트웨어 시스템이나 애플리케이션의 주 작성자가 비교적 비공식 문서를 만든다고 하는데, 설계 자체가 코딩 프로젝트이고 둘은 같은 일임
    코드를 커밋하기 전에 종이 위에서 설계를 다 풀 수 있다는 생각은 틀렸음. 설계 문서 접근도 사실 초기에 코드를 좀 써야 한다는 점은 인정하지만, 이를 “설계 구현 가능성을 보여주는 프로토타입”으로 엄격히 구획하려 함
    사전 설계 문서의 큰 특징은 본격적인 코딩 전에 사람들이 트집 잡기, 즉 리뷰를 할 수 있도록 허가한다는 것임. 내 경험상 그러면 문서가 점점 더 많은 단서와 무의미한 대안 논의로 늘어나고, 설계 문서라기보다 “제발 이제 이걸 만들게 해줘” 문서가 됨
    방향 전환이 필요한 중요한 아키텍처 문제가 있다면, 자세한 설계 문서를 만든 뒤 격추당하기보다 사전에 알맞은 사람들과 이야기하고 협업하는 편이 낫음
    “비교적 비공식 문서”라는 생각에 더 가깝게 유지하고 진행하면서 문서를 갱신한다면 실제로 유용할 수 있음. 작동하는 시스템과 유용한 문서를 함께 만들 수 있기 때문임. 다만 그건 설계 문서라기보다 지속적이고 협업적인 과정의 일부로 문서화하는 것에 가까움

    • 프로젝트가 충분히 크고 잘 생각된 것이라면, 전체 작업량에 비해 큰 추가 비용 없이 아키텍처 변경을 반영할 수 있음

  • Googler임. 논문도 여러 편 냈지만 설계 문서 쓰는 걸 예전에는 싫어했음. 몇 년 전부터 나에게 주는 주된 이점을 깨달았음
    아이디어의 즉각적인 부분을 머릿속에서 비워 더 깊은 부분과 생산적인 고려로 넘어가게 해줌
    결함이 더 잘 보이고, 특히 나 자신에게 잘 보임
    생각을 공유하기 쉬워지고, 특히 다른 사무실 사람들에게 공유하기 좋음. 그들은 보통 아주 좋은 피드백을 줌
    그냥 코딩을 시작할 때보다 필요한 작업량을 훨씬 잘 파악하게 해줌
    코딩 전에 배워야 할 것들, 인접 시스템이나 적절한 기술 선택 등을 대개 드러내 줌
    승진에도 좋긴 하지만, 성공한 프로젝트가 더 좋음. 내 문서가 유용하다는 말을 자주 듣기 때문에 뭔가 맞는 길을 찾은 듯함

    • 나도 같음. 설계 문서의 가장 큰 수혜자는 내 사고 과정이었음. 전 Googler임

  • 실제로 효과가 있나? 대안보다 나은가? 그 논의는 어디 있나?
    Amazon에서 일했을 때 설계 문서 문화는 훌륭했음. 다음 직장은 Google의 엔지니어링 문화나 SF의 일반적인 스타트업 문화를 빌려온 듯했는데, 설계 문서 절차는 쓸모없는 농담 같았음

    • 설계 문서는 논의의 수단임. 의도, 동기, 왜 다른 대안을 택하지 않았는지를 가장 효율적으로 전달하는 방법이라는 아이디어임
      더 넓은 업무 문화에 맞물린 하나의 장치임. 혼자 일한다면 사치스러운 연습이고, 거대한 팀이라면 팀 전체의 더 많은 전문성을 활용하게 하고 문서 역할도 함
      실패 양상은 몇 가지 있음. 결과보다 산출물을 중시하는 건 전형적인 불일치임. 승진을 위해 40쪽 문서를 쓰는 식인데, 깊은 엔지니어링보다 문장을 이어 붙일 수 있음을 증명하는 아주 주니어한 경우가 아니면 잘 통하지 않음
      혼자 일하는 팀에는 과하다는 점도 있음. 다른 소규모 팀은 이슈, 예컨대 Jira와 아이디어를 맞춰보는 별도 세션만으로도 충분히 소통 가능함
      엔지니어도 효과적인 설계 문서 작성법에 온보딩되어야 함. 첫 시도가 즉시 찬사를 받지 못했다고 좌절한 상위 댓글은 신호일 수 있음
      코드에 대해 글쓰기는 어렵고, 보통 HN에서는 이런 연습을 칭찬함. 팀에서 일한다면 자신의 일이 항상 공유 가능한 문서로 설명하고 깊이 생각할 필요가 없는 일뿐이라고 느껴질 때 조심해야 함
    • Amazon 설계 문서 문화에서 어떤 점이 가장 좋았는지 궁금함

  • 큰 투자자가 신분을 숨기고 몇 주 동안 Google 엔지니어로 일해본다면, 곧바로 Sundar의 해임을 요구하는 행동주의 투자자가 될 것임
    Google의 설계 문서 문화 때문에 낭비되는 인간 잠재력의 규모는 거의 이해하기 어려울 정도임

    • 대부분의 설계 문서에 들어가는 노력을 사람들이 크게 과대평가하는 것 같음
      대부분의 개발은 그냥 진행되고, 가끔 CL을 정당화하기 쉽게 하려고 문서를 급히 써냄
      10개 중 하나 정도에서 누군가 지나치게 과하게 한 걸 보지만, 평균적인 소프트웨어 엔지니어에게는 큰 시간 낭비가 아님
    • Carl Icahn이 그런 일에 딱 맞는 사람임. https://www.bloomberglinea.com/english/i-fired-12-floors-of-...
    • 내 가설은 후기 Google이 독점 이익을 숨기도록 설계됐다는 것임
      가능한 한 많은 돈을 태우고 싶다면 회사를 정확히 이렇게 설계할 것 같음

  • 설계 문서 문화는 모두를 자기 일에 대한 정당화 계층으로 밀어 넣는 경향이 있음. 정당화 문화는 동료들이 문화로 강화하더라도 혁신가에게 상당히 억압적인 패턴임
    이 시스템은 비전 있는 시도와 포부 큰 프로젝트를 막는 경향이 있음. 합의 중심이 아닌 노력은 억눌리고, “허용된 규범 밖”을 생각하면 집단에게 벌받게 됨
    이런 시스템은 집단사고를 낳고, “우리가 일하는 방식”이라는 전통 중심 성격은 다른 방식으로 일하는 것이 경력에 위험해지는 상황을 본질적으로 강제함
    실리콘밸리에는 ‘애자일’과 ‘디자인 사고’ 용어로 포장된 상투어에 기대는 회사 문화가 온갖 형태로 있고, 대개는 ‘올바른 방식’인 척하는 제도화에 가깝고, 그 캠퍼스가 도달한 엔지니어링 컬트 문화 변형을 사회적으로 강제하는 부가 요소가 따라옴
    Google에서 일하는 게 매우 편했는데도 경력에 제약이 된다고 떠난 사람을 셀 수 없을 만큼 만났고, 적은 수가 아님

    • 그래서 보수를 그렇게 많이 주는 것임. 함정임. 그리고 그곳에서 일한다는 겉보기 지위도 있었지만 지금은 대부분 희미해짐
      내가 그곳에서 겪은 좌절을 정확히 표현해 줬음. 그래도 그 보수는 다시 받고 싶긴 함
      애자일에 관해서는, 나는 약 20년 전 eXtreme Programming 형태로 애자일을 접했는데, 오늘날 SCRUM이나 그 모방품이라는 화물 숭배와는 전혀 달랐음
      결국 개발자에게 창의적 힘을 주고 관리자가 방법에 끼어들지 못하게 하며 일을 해내게 하는 원칙들의 묶음이었음. 대신 고객에게 무엇을 언제, 어느 정도 할지 말할 권한을 줌
      개발자가 직접 추정하고, “필요하지 않을 것은 만들지 않는다”가 원칙임. 큰 사전 설계는 없고, 리팩터링과 테스트, 아키텍처와 설계는 별도 스토리나 작업이 아니라 표준 모범 관행으로서 지속적인 오버헤드에 포함됨
      계획 회의는 동료들이 방에서 맞춰보는 것이고, 스토리는 화이트보드의 포스트잇에 최소한의 비기술 용어로 표현됨. 스탠드업은 실제로 사람들이 원형으로 서서 다른 사람이 관심 있을 수 있을 만큼 아주 짧게 업데이트하는 것이지, 오늘 출근했음을 증명하거나 과시하는 의식이 아님
      이 시스템에서 설계는 전문가들의 창의적 집단이 함께 일하며 생겨나는 속성임. 설계 문서를 배제하지 않고 아키텍처 논의도 여전히 포함하지만, 명시적인 PRD/설계 문서 절차를 요구하지는 않음
      그런 곳에서 다시 일해보고 싶음. Google은 정반대였고 모든 일이 너무 오래 걸렸음
    • 그래서 Google은 제품을 전혀 만들지 못하는 것임. 어제 새 Pixel 7이 고장 났음
      이런 가짜 “우리는 매우 똑똑하다”식 행동도 헛일의 한 형태임. 회사는 실제로 작동하는 제품에 집중하고 그것으로 스스로를 평가해야 함

  • 또 다른 Googler임
    Google의 설계 문서가 쓸모없다는 좋은 댓글이 이미 많지만, 문제로 느끼는 관점을 하나 더 보태고 싶음
    설계 문서는 언급된 것처럼 승진 자료라서 엄청난 군더더기를 낳음. 그런데 실제 문서화를 대체하는 것처럼 보이기도 함
    모든 설계 문서는 완성되는 순간 거의 낡아버리지만, 팀들은 문서를 새로 쓰는 대신 그 설계 문서를 가리킴. 결과적으로 Google의 문서화는 꽤 나쁘고 오래되어 있음
    솔직히 “하지 않은 일”에 대해 20쪽을 쓰는 것보다, 실제 존재하는 것을 어떻게 쓰는지 2쪽짜리 사용 설명을 쓰는 게 승진 자료였으면 훨씬 좋았을 것임

  • 실제 문서를 볼 수 있나? 소프트웨어 설계 프로세스 문서는 가장 철저히 지켜지는 비밀처럼 보임. 사례 연구에 쓸 수 있는 실제 문서를 본 적이 없음

답변달기