아마존 출신 엔지니어, "설계 문서는 수학의 증명과 같아야" 주장...IT 업계 '문서 작성 문화' 확산 위한 실무 가이드라인 제시

[한국정보기술신문] 그랜트 슬래튼(Grant Slatton) 전 아마존 엔지니어가 효과적인 설계 문서 작성 방법론을 제시해 IT 업계의 주목을 받고 있다. 슬래튼은 자신의 개인 블로그를 통해 "설계 문서는 수학의 증명처럼 독자를 설득하는 것이 목표"라고 강조하며, 체계적인 문서 작성 가이드라인을 공개했다.

설계 문서의 본질과 목적

슬래튼에 따르면 설계 문서는 "제약과 트레이드오프를 고려한 시스템 구현 전략을 설명하는 기술 보고서"로 정의된다. 그는 설계 문서의 목표를 수학의 증명에 비유하며, "수학 증명이 정리가 참임을 독자에게 확신시키는 것처럼, 설계 문서는 주어진 상황에서 해당 설계가 최적임을 독자에게 확신시켜야 한다"고 설명했다.

특히 가장 중요한 독자는 작성자 자신이라는 점을 강조했다. 문서 작성 과정 자체가 막연한 직감을 엄밀한 논리로 발전시키는 역할을 하며, "글쓰기는 사고가 얼마나 엉성했는지 드러내고, 나중에 코드는 글쓰기가 얼마나 엉성했는지 보여준다"고 표현했다.

슬래튼은 좋은 설계 문서의 구성이 코드 구성만큼 중요하다고 강조했다. 그는 프로그래밍 초보자들이 코드 실행 순서를 고려하지 않고 "스파게티 코드"를 작성하는 것처럼, 대부분의 엔지니어들이 문장과 문단의 순서를 고려하지 않은 "스파게티 설계 문서"를 작성한다고 지적했다.

완벽한 문서는 독자가 결코 놀라지 않도록 작성되어야 한다는 것이 그의 철학이다. "독자는 모든 문장이 이전 문장들로부터 자연스럽게 이어진다고 느껴야 하며, 문서를 읽고 나서 '이건 완전히 당연한 내용인데, 왜 회의까지 해야 했나?'라고 생각해야 한다"고 설명했다.

독자 중심의 사고와 선제적 대응

효과적인 문서 작성을 위해서는 독자의 마음 상태를 정확히 모델링하는 것이 필수적이라고 슬래튼은 강조했다. 문서의 목표는 독자의 현재 상태에서 설계안이 좋다고 믿는 새로운 상태로 마음을 이끄는 것이다.

이를 위해 독자가 제기할 수 있는 모든 반박을 예상하고, 독자가 그런 생각을 하기도 전에 미리 그것이 왜 타당하지 않은지 보여줘야 한다고 제안했다. 많은 엔지니어들이 독자의 출발점을 제대로 파악하지 못해 목적지까지 이끌지 못한다는 것이 그의 분석이다.

정보를 적절히 구성한 후에는 편집을 통해 길이를 줄이는 것이 중요하다고 슬래튼은 강조했다. 독자의 주의력은 희소한 자원이므로 제거할 수 있는 모든 단어를 제거해야 한다는 것이다.

일반적으로 첫 번째 초안에서는 정보 손실 없이 약 30%의 분량을 줄일 수 있다고 그는 설명했다. 편집 실력을 향상시키는 가장 쉬운 방법은 다른 사람의 문서를 빨간 펜으로 교정하며 불필요한 단어들을 찾아내는 것이라고 조언했다.

아마존의 독특한 문서 문화 경험

슬래튼은 아마존에서의 독특한 문서 작성 문화 경험을 공유했다. 아마존의 회의는 발표자가 1-6페이지 분량의 산문 문서를 배포하는 것으로 시작된다.

회의 참석자들은 조용히 앉아 문서를 읽으며 빨간 펜으로 여백에 메모와 질문을 적는다. 정성스럽게 작성한 문서에 다른 사람들이 표시를 하는 모습을 지켜보는 것은 더 나은 작성자가 되도록 하는 강력한 동기가 된다고 그는 회상했다.

슬래튼은 몇 가지 구체적인 작성 기법을 제안했다. 첫째, 짧은 문단을 사용하라는 것이다. 문서를 서로 연결되는 일련의 요점들로 생각해야 하며, 각 요점은 한 문장으로 요약될 수 있는 문단이어야 한다.

둘째, 부록을 활용하라고 조언했다. 복잡한 계산이나 시뮬레이션 결과가 포함된 수치가 있다면 본문에 포함하지 말고 각주를 사용해 부록에서 자세히 설명하라는 것이다. 부록은 문서의 주요 결론을 이해하는 데 필수적이어서는 안 되며, 호기심 많은 독자가 작업을 확인하고 싶을 때만 참조하는 용도여야 한다.

실제 편집 사례를 통한 학습

슬래튼은 자신의 편집 과정을 실제 사례로 보여줬다. 원래 버전은 "각각의 요점들은 문서에서 독립된 문단이 되어야 한다. 그리고 각 문단은 한 문장으로 요약될 수 있어야 한다. 문단이 실제로 한 문장일 필요는 없다. 예를 들어, 전달하려는 전체 개념을 정말로 설명하기 위해 몇 문장을 더 포함할 수 있다. 하지만 독자가 읽고 나면, 그들의 마음속에서 한 문장으로 압축할 수 있어야 한다"였다.

편집 후 버전은 "각 요점은 한 문장으로 요약될 수 있는 문단이어야 한다. 한 문장일 필요는 없으며, 필요한 경우 자세히 설명할 수 있다. 하지만 읽고 나면 독자는 그것을 마음속에서 한 문장으로 압축할 수 있어야 한다"로 동일한 정보를 더 간결하게 전달했다.

슬래튼은 많은 연습이 필요하다고 강조했다. 그는 아마존의 독특한 문서 작성 문화 덕분에 처음 작성한 문서들은 형편없었지만, 수백 개의 문서를 작성한 후에는 꽤 좋아졌다고 회고했다.

280자 트위터 제한에 맞춰 생각을 압축하는 연습도 놀랍도록 좋은 훈련이 된다고 조언했다. 이러한 제약이 간결하고 명확한 표현 능력을 기르는 데 도움이 된다는 것이다.

슬래튼의 가이드라인은 IT 업계의 오랜 과제인 기술 문서의 품질 향상에 대한 실용적 해답을 제시한다. 많은 기술자들이 코딩에는 뛰어나지만 문서 작성에는 어려움을 겪는 현실에서, 체계적인 접근법이 절실했던 상황이다.

특히 원격 근무가 일반화되면서 명확한 문서 커뮤니케이션의 중요성이 더욱 부각되고 있다. 슬래튼의 방법론은 단순히 문서 작성 기술을 넘어 사고의 체계화와 논리적 설득력 향상에도 기여할 것으로 기대된다.

한국정보기술신문 교육분과 정수민 기자 news@kitpa.org