▲

좋은 설계 문서 작성법

 (grantslatton.com)
33P by GN⁺ 2일전 | ★ favorite | 댓글 1개
  • 설계 문서는 시스템의 구현 전략과 제한사항, 트레이드오프를 정리한 기술 보고서임
  • 설계 문서는 독자가 해당 설계가 상황에 적합하다는 점을 납득하도록 설득하는 역할임
  • 문서의 구성이 중요하며, 논리적인 흐름을 통해 독자가 내용에 놀라지 않도록 해야 함
  • 편집을 통해 불필요한 단어를 줄이고, 독자의 집중력 자원을 아끼는 것이 필요함
  • 짧은 단락과 부록 활용, 연습을 통한 문서 작성 역량 향상이 중요함

정의

  • 설계 문서는 시스템 구현 전략을 트레이드오프와 제약 조건 맥락에서 정리한 기술 보고서임

목표

  • 설계 문서는 수학에서 증명이 정리를 납득시키는 것과 같이, 해당 설계가 최적임을 독자에게 설득하기 위한 목적을 가짐
  • 설계 과정에서 작성 자체가 사고의 엄밀성을 높임
  • 설계 문서를 작성하며 막연한 생각을 구체적 사고로 바꿀 수 있음

조직화

  • 좋은 설계 문서의 구성은 코드 조직화만큼이나 중요함
  • 초보자들이 코드를 쓰듯, 많은 사람이 '스파게티 설계 문서' 를 작성하는 경향이 있음
  • 논리적 순서 없이 문장을 나열하면, 독자가 맥락을 따라가기 어렵고 혼란을 느낌
  • 완벽한 문서는 독자가 놀라지 않도록 흐름이 자연스러워야 하며, 각 문장이 이전 내용을 토대로 당연하게 이어져야 함
  • 독자의 사고 상태를 파악하여, 단계적으로 새로운 상태로 인도하는 것이 목표임
  • 예상 가능한 이의제기를 사전에 해소해야 하며, 독자가 반론을 제기하기 전에 설명해야 함

편집

  • 내용을 잘 조직한 후에는 불필요한 단어 제거(편집) 단계가 중요함
  • 독자의 집중력은 한정된 자원이며, 불필요한 정보는 과감히 삭제가 필요함
  • 초안에서 무의미한 표현을 약 30%는 줄일 수 있음
  • 타인의 문서를 편집하며 비판적 시각을 기르면, 자신의 글도 효율적으로 다듬을 수 있음
  • 짧은 트윗(280자 제한) 으로 연습하는 것도 사고 단순화와 압축 능력 향상에 도움을 줌

경험과 연습

  • 반복 연습만큼 실력을 키우는 지름길은 없음
  • Amazon에서의 문서 중심 문화 경험은 문서 작성 역량 향상에 큰 도움이 되었음
  • 중요한 회의에서는 1~6페이지 규모의 설계 문서를 배포한 후, 모두가 조용히 읽고 여백에 의견을 적는 방식을 사용함
  • 피드백을 받으며 글쓰기 실력을 실질적으로 높일 수 있음

구체적 팁

짧은 단락 사용

  • 설계 문서는 연속된 간결한 bullet point로 흐름을 만들어야 함
  • 각 bullet point(관찰, 아이디어, 문제점, 개선 등)는 한 개념에 집중된 짧은 단락으로 구성함
  • 각 단락은 한 문장으로 요약할 수 있을 정도의 명확성을 가져야 하며, 이로 인해 독자의 단기 기억 자원을 절약할 수 있음

부록 활용

  • 복잡한 계산이나 시뮬레이션 결과는 문서 본문이 아닌 부록에 자세히 정리하고, 본문에는 간단한 각주 형태로 언급함
  • 본문의 주요 결론 이해에 부록은 필수적이지 않으며, 궁금한 독자가 참고할 수 있도록 제공함

편집 예시

  • (편집 전, 장황한 단락):

    각 bullet point는 문서에서 별도 단락이 되어야 한다. 각 단락은 한 문장으로 요약 가능해야 한다. 실제로 한 문장이 될 필요는 없으며, 개념을 설명하기 위해 추가 설명이 들어갈 수 있다. 하지만 독자가 읽은 후엔 한 문장으로 요약 가능해야 한다.

  • (편집 후, 간결화된 단락):

    각 bullet point는 한 단락으로, 한 문장으로 요약될 수 있어야 한다. 실제로 한 문장이 아니어도 되며, 필요하다면 부연 설명을 추가할 수 있다. 하지만 읽고 나면 한 문장으로 압축될 수 있어야 한다.

마무리

  • 설계 문서는 사고의 엄밀성, 논리적 흐름, 독자 중심 편집, 반복 연습을 통해 역량을 키울 수 있는 중요한 과정임
▲
GN⁺ 2일전  [-]
Hacker News 의견
  • 기사에서 특히 인상 깊었던 인용문 두 가지를 소개함. 첫 번째는 X의 스크린샷에서 "글을 쓰는 과정에서 아이디어가 10배 더 좋아짐"이라는 문구임. 두 번째는 시작 부분에서 "설득해야 할 가장 중요한 사람은 저자 자신임"이라는 말임. 수년간 업계에서 일했어도 여전히 디자인 문서의 필요성에 반대하는 사람들이 있어 놀라움. Leslie Lamport가 "글쓰기는 우리 사고가 얼마나 엉성한지 자연이 말해주는 방식"이라고 했음. 기술 글쓰기 능력을 더 키우고 싶다면, Write Like an Amazonian(https://medium.com/@apappascs/…) 글을 추천함
    • "형용사를 데이터로 바꾸라"는 조언이 기술 업계 전반에 퍼져서 그런지, 요즘 보는 이력서마다 수치로 가득해 어떤 의미인지 헷갈릴 정도임
  • 디자인 리뷰어로서, 모든 문서 작성자가 반드시 내면화해야 할 점이 있음. "좋은 문서는 문제와 사고 모델을 독자가 이해하게 하여, 수주간의 고민 끝에 탄생한 해법이 딱 소개될 때 자연스럽게 수긍하게 만들 수 있음"이라는 부분임. 내가 가장 좋아하는 인용구는 "시간이 더 있다면 더 짧은 편지를 썼을 것임"임. 디자인 문서는 복잡한 내용을 단순하게 만들어야 하며, 개발자가 겪은 모든 우여곡절과 실패를 무작정 담는 곳이 아니라고 생각함. 이런 내용도 물론 담을만하지만, 별도의 문서나 부록 등에 정리하는 것이 좋음. 앞으로 나아갈 길을 간단하게 보여줄 필요가 있음
    • "더 많은 시간, 더 짧은 편지"라는 표현을 더 선호함
    • 항상 이런 질문을 스스로에게 던짐: "이 주제에서 괜한 논쟁이 발생할까?", "논쟁을 할 만한 가치가 있는가?" 내 목표는 새로운 독자가 어렵지 않게 논의에 참여할 수 있도록 하고, 중요하지 않은 부분에 대해서는 논란이 생기지 않게 하는 것임
  • Amazon 회의는 발표자가 산문 형태의 문서를 나눠주면서 시작함. 모두가 조용히 앉아서 문서를 읽고, 여백에 빨간 펜으로 메모와 질문을 적음. 실제로 Amazon에서 일해본 적은 없지만, 이 방식이 신기할 정도로 효과적이고, 실제로 이 경험을 말하는 사람들은 다들 좋아함. 귀중한 회의 시간을 다 같이 읽고만 있으니 비효율적일 것 같지만, 사실 사전에 읽고 준비하면 더 짧은 회의가 가능할 것임. 실시간 동시 읽기는 느린 독자를 기다리거나, 맥락이 부족해 이해도가 다르기 때문에 모두가 모호하게 시간을 보내게 됨. Google에서 디자인 리뷰를 할 때 참석자 대부분이 준비 없이 처음 문서를 보고 토론에 참여하는 모습을 자주 봤음. 이건 구글이 강한 문서 문화가 없었고, 팀 리드나 매니저도 준비 없이 오는 것을 암묵적으로 용인했기 때문이라고 생각함. 회의 전에 확실히 읽고 오도록 문화만 잘 자리잡아도, 회의 시간이 훨씬 효율적으로 쓰일 수 있을 것으로 보임
    • 사람들은 회의 전에 미리 읽어오면 회의 시간이 줄어든다고 말하지만, Amazon의 관행은 사람들이 실제로는 미리 읽어오지 않는다는 현실에 대한 대응임. 예전 관련 기사에서 보니, 사전에 읽고 준비하는 강한 문화를 만드는 것이 사실상 불가능했다고 함. 모든 참석자가 바로 앞 회의 때문에 사전에 준비를 못 했고, 그 앞 회의도 있었기 때문임. 이론적으로는 회의 수를 줄이면 되지 않냐는 비판도 가능하지만, 실제로는 회의가 가치가 있었고, 읽는 시간 포함해도 충분히 결정이 이뤄졌다고 함. 결국 결과에 집중할 필요가 있으며, 실제로 Amazon에서는 이 방식의 장점이 단점보다 크다고 느끼는 듯함
    • 언제 문서를 읽느냐가 왜 중요한지 의문임. 만약 시간이 더 필요하면 회의 시간을 늘릴 수 있음. 단점이라면 회의 일정 잡기가 어렵다는 건데, 총 소요 시간은 변하지 않는다는 의견임
    • 모두가 동일한 이해 수준이 아니거나, 누군가의 코너 케이스를 놓칠까 걱정할 때 더 많은 시간이 낭비된다고 생각함
    • 실제로 회의에서 다루지 않으면 아무 일도 일어나지 않는다는 경험을 얘기함
  • 명확성과 편집에 대한 훌륭한 조언이 많음. 약점은 문서가 승인된 이후 어떻게 관리하느냐임. 관리가 없다면 '디자인 고고학' 상태로 퇴화하게 됨. 몇 년 전 Andrew Harmel-Law가 조직 내에서 아키텍처 의사결정을 효과적으로 기록하는 방법으로 Architecture Decision Records(ADRs)를 제안했는데, 이 방식이 도움이 될 수 있음. ADRs는 코드 옆에(예: adr/001-use-postgres.md) 있고, 맥락과 결정, 그리고 상태를 짧게 기록함. 그래서 PR마다 쉽게 검토할 수 있고, 상황이 바뀌면 쉽게 대체할 수 있다는 점이 장점임. 원래 의사결정의 근거도 수개월이 지나도 검색할 수 있게 됨. [링크: https://martinfowler.com/articles/…]
    • 이런 방식이면 Security, Privacy, Compliance 등 전체 조직의 위원회들이 모든 ADR이 걸린 PR마다 검토자가 되는지 궁금함. 그런 PR이 90일 이내에 머지될 수 있는지 의문임
    • MF.com(https://thoughtworks.com/radar/techniques/…) 링크를 완전히 읽어봐야겠지만, "Advice Process"는 '모두와 이야기하라'라는 문장으로 끝나버림. 'Managing'이란 직함을 달고 있는 사람은 이쯤에서 관심을 잃을 것 같음. 진짜 핵심은 "네 가지 지원 요소"인데, ADRs를 더 알아보려고 이 링크로 들어갔다가, 결국 PDF(https://thoughtworks.com/content/dam/…)를 받게 됨. 실제로 ADRs가 무엇인지 정의를 명확하게 알려주면 좋겠음
    • Session messenger가 대표적인 예시임. 수많은 디자인 및 아키텍처 변경이 있었기 때문에 어떻게 동작하는지 공식적으로 설명해주는 권위 있는 정보가 없음. 참고로 보안 메시징이 필요하다면 그냥 Signal을 쓰면 됨
  • 내 경험상, 조직과 명확성은 SW 엔지니어들이 문서 작성 실력을 늘리는 데 가장 큰 장애물임. 저자의 '코드 스파게티' 비유가 아이디어 조직의 중요성을 설명하기에 좋은 예라고 생각함. 나도 비슷한 얘기를 다른 식으로 전하려 한 적이 있었는데, 앞으로 이 비유를 쓸 계획임. 예전에 비슷한 블로그 글을 쓴 적 있는데(https://ryanmadden.net/things-i-learned-at-google-design-docs/), 정보 밀도와 실습의 중요성 등 공통점과 업체에 따라 다른 점이 흥미로웠음. '짧은 문단' 주장에 대해서는 살짝 다르게 생각함. 정보가 잘 다듬어져야 짧은 문단이 나오지, 줄만 바꾼다고 도움되는 것은 아님. 'Editing' 부분이 그 밑바탕 아이디어를 더 잘 설명해주고 있다고 생각함
  • 내가 쓰는 한 가지 프로세스가 있음. 1단계: 생각나는 것을 아무렇게나 문서에 쏟아냄(말로 받아쓰기를 써봐도 좋음). 2단계: LLM(대형 언어 모델)로 구조와 흐름을 잡게 시도함. 사실 이 단계에서 결과물을 버릴 수도 있으며, 계속 생각을 다듬는 과정임. 3단계: LLM 결과를 참고하거나, 아예 새로 아웃라인을 짜서 첫 초안을 작성함. 4단계: 단어 줄이기, 쉬운 단어로 바꾸기 등 최대한 간결하게 만듦. 5단계: 4단계 반복함. LLM은 두서없는 초안을 구조화해주는 다리 역할을 해줌. LLM이 내놓은 내용을 버릴 각오도 필요함. 최소 30%는 항상 줄일 수 있음. 실제로 줄이면서도 의미를 잃지 않는 걸 볼 때마다 놀라움
    • 내 글을 다시 편집하는 과정이 글을 처음 쓰는 것만큼이나 중요하다고 느낌. 이때 내가 얼마나 결론을 성급하게 내렸는지, 고려 안 한 점은 무엇인지 파악하게 됨. 많은 사람이 글쓰기를 사고의 집중화 도구로 충분히 가치 있게 평가하지 않는 듯함. 코드도 마찬가지임. 단순한 템플릿 작성한다고 쳐도, 테스트 코드를 작성하며 메인 코드를 개선할 아이디어가 떠오를 때가 많음. 하지만 LLM이 이런 정성적인 개선의 기회를 알려주진 않음
    • 확장, 축약, 압축, 다시 확장, 다시 압축 반복임. 누군가 구체적인 질문을 하면 다시 확장하고, 마지막엔 LLM을 사용해서 재미를 위한 부담 없는 요약을 하게 됨. 우리는 진짜 끝도 없는 롤러코스터를 타고 있는 셈임
  • 글쓰기를 더 많이 해야겠다고 생각함. 내가 생각하는 대표적인 문서 구조법은 B.O.O.와 Good Strategy/Bad Strategy임. B.O.O.는 Background, Objective, Overview의 약자로, 어떤 흐름으로 여기까지 왔고, 무엇을 어떻게 바꾸려고 하는지 정리하는 것임. Good Strategy/Bad Strategy는 진단, 가이드라인/전제조건/요구사항, 그리고 액션으로 구성된 책인데, 문서 조직 측면에서 B.O.O.와 유사함. B.O.O.는 Google이나 구성원이 작은 조직에서 잘 맞고, Good Strategy/Bad Strategy는 훨씬 다양한 규모에 적용 가능하지만 필력 있는 저자가 필요함
  • 기술 글쓰기 수업을 들으면서 요점을 명확하게 요약하는 능력이 크게 향상됨. '빨간 펜으로 자르기' 방식(글을 쓰고, 줄을 긋고, 다시 쓰기)에 집중했는데, 최대한 적은 단어로 개념을 전달하는 법을 강조함. 이 과정은 여러 단계로 나뉘고, 연습할수록 더 쉬워짐. 이런 역량은 팀원들과도 공유하려 하지만, 정기적으로 훈련해야 하는 스킬임을 항상 상기함
  • 이런 식으로 작성된 문서와 글쓰기 문화 자체를 정말 좋아함. 하지만 이런 접근 방식이 역효과를 낳는 경우도 봄. 이 방식을 통해 결론에 이르는 이유와 논리를 설명하는 것이 설득형 문서에는 매우 효과적임. 그렇지만 항상 그런 식의 설득이 필요하지 않은 경우도 많음. 때로는 결론부터 직접적으로 써주는 것이 오히려 독자, 특히 작성자를 신뢰하는 독자들에게 더 좋음. 많은 경우 독자는 논리를 따라가느라 지치는 대신, 요점부터 알고 싶어함. 일단 결론을 알게 되면 그제야 세부 논리를 따라가고 싶어짐
    • 위에 요약을 달고, 세부 설명과 근거를 아래에 이어가는 구조도 충분히 괜찮음
  • 나만 읽게 될지도 모를 디자인 문서를 직접 쓸 때가 종종 있음. 문서를 글로 남기는 것만으로도 강력함을 느낌. 실제 예시 문서가 있다면 정말 도움이 될 것 같은데, 내 문서 구조와 다른 사람들의 최종 구조를 비교해보고 싶음
답변달기