해당 포스트는 how-to-write-a-good-software-design-document의 한글 번역 포스트입니다.
저는 소프트웨어 엔지니어로서, 어떤 형태의 문서든 설계문서를 읽거나 쓰는데에 많은 시간을 보냅니다. 지금까지 저는, 성공적인 소프트웨어 개발 프로젝트와 좋은 디자인 문서는 강한 상관관계가 있다는 결과를 많이 목격 해왔습니다.
이 포스트는, 어떤 요소들이 좋은 설계문서를 만드는지 에 대해 설명 하려고 작성하였습니다.
총, 4개의 섹션으로 나누어져 있습니다.
- 설계 문서를 작성하는 이유.
- 어떤 내용이 설계문서에 포함되는지.
- 작성 방법.
- 관련된 프로세스.
1. 설계문서는 왜 만드나요?
설계문서(aka.테크니컬 스펙)는 문제 해결 방법/계획에 대해 설명하는 문서입니다.
코드를 작성하기 전에 디자인 문서를 작성하는 것이 왜 중요한지에 대한 포스트는 이미 많이 존재합니다. 이외에, 제가 이 포스트에서 이야기 하려고 하는 것을 한 문장으로 정리하자면 아래와 같습니다.
설계문서는 올바른 작업을 수행하는데 있어 가장 유용한 도구이다.
설계 문서의 주요 목표는 디자인에 대해 문서로 작성 할 수 있는 수준으로 작성자가 고민하게 강제하는 것과 다른 사람으로 부터 피드백을 수집하여, 좀 더 완성도 높은 개발 결과물을 만들 수 있게 하는 것입니다. 일반적으로 대부분의 사람들은 다른사람들에게 시스템에 대해 알려주기 용이하기 때문에, 기록으로 남김으로써 나중에 다시 찾아보기 위해 필요하기 때문에 설계문서를 작성 해야한다고 생각하지만, 이는 주요 목표가 아닙니다.
일반적으로, 엔지니어가 1 개월 이상 소요될수 있는 프로젝트를 작업하는 경우 설계문서를 작성 해야합니다. 그렇다고 해서 작은 작업일 때 필요 없다는 말은 아닙니다. 작은 규모의 작업시에도 설계문서 작성의 이점을 충분히 누릴 수 있습니다.
좋습니다 좋아요! 여기까지 이 포스트를 읽고 계신다면, 디자인 문서의 중요성에 대해서 믿음을 갖고 계신 분이시네요. 실제 설계문서를 접해보신 분들 이시라면, 다양한 형태의 설계문서를 보셨을 것 같습니다. 아래에서는 다양한 형태의 설계문서 속에서도 좋은 내용, 스타일, 프로세스가 무엇인지 설명하려 합니다.
2. 설계문서에는 어떤 내용이 있어야 하나요?
위에서도 언급 하였듯이 설계문서는 문제에 대한 솔루션을 설명합니다. 해결하려는 문제의 성격에 따라 설계문서의 구조를 다르게 구성하는 것이 좋습니다.
최소한 포함 되어야 할 항목은 아래와 같습니다.
제목과 사람
- 디자인 문서의 제목.
- 작성자. (작업을 담당한 사람과 동일 해야 함)
- 문서 검토자. (프로세스 섹션에서 자세하게 설명 됨)
- 최신 업데이트 날짜.
개요
다른 엔지니어들이 문서의 나머지 부분을 이어서 읽어야 할지 결정 하기 위해, 높은 수준으로 요약 되어야합니다. 최대 3개 문단으로 구성 되는것이 권장됩니다.
문맥
- 직면한 문제가 무엇인지에 대한 설명.
- 이 작업이 필요한 이유.
- 이 작업 내용을 평가하기 위해 알아야할 사항
- 이 작업이 만족시키는 기술 전략.
- 팀의 목표에 어떻게 부합하는지.
목표
- 사용자(엔지니어 일 수도 있음) 관점에서의 결과물의 가치
- 성공 여부를 측정 하는 방법에 대한 설명.
목표가 아닌 것
이 작업으로 수정하지 않을 문제를 설명 하는 것도 매우 중요합니다.
마일스톤
PM과 관리자가 마일스톤의 내용을 확인하고, 대략적인 완료일을 알 수 있도록 체크포인트를 명시하여 작성합니다. 작업의 크기가 1개월 이상인경우 주요 사용자 별 마일스톤으로 나누어 작성하는것이 좋습니다.
날짜를 사용 하여 표현 함으로써, 휴가, 회의 일정 과는 관계없이 작성하는 것이 좋습니다.
시작 일자 : 2018. 7. 7.
마일스톤1 — MVP 기능 개발 완료: 2018. 6. 28.
마일스톤2 - 기존 시스템 중단: 2018. 7. 30.
완료 일자 - 신규 시스템에 기능 추가: 2018. 8. 10.
이러한 마일스톤 중 일부의 ETA가 변경되는 경우, 변경된 마일스톤에 대해 하위 섹션[Update]을 추가하면 이해 관계자가 최신 추정치를 쉽게 볼 수 있습니다.
기존 솔루션 (신규기능 추가가 아닌 경우)
현재 구현된 사항을 설명합니다. 사용자가 시스템과 인터렉션 하는 방법과 인터렉션 시에 데이터가 변경 되는 흐름을 설명 해야 합니다. 이해를 돕기 위해, 충분한 예제를 포함하는 것이 좋습니다.
유저 스토리는 이를 위한, 좋은 프레임입니다.
제안하려는 솔루션
가장 중요한 내용입니다. 어떻게 문제를 해결 할 수 있는지가 모두 설명 되어야 합니다. 이 또한 사용자스토리 프레임으로 설명 되면 좋습니다. 많은 하위 섹션들과 다이어그램을 포함 하여 이해를 높여야 합니다.
큰그림을 가장먼저 제시 하세요. 작성자가 휴가를 가더라도 이 섹션을 다른 엔지니어가 보고 그대로 구현 할 수 있도록 작성하세요.
대체 솔루션
위의 솔루션을 대체 할 다른 대안이 있다면 무엇이 있는지 간단하게 나열 해봅니다. 오픈소스를 사용한다거나 구매 할 수 있는 솔루션을 고려 할 수도 있습니다.
테스트 가능성, 모니터링 및 경고
개인적으로 이 섹션이 포함 되는것을 추천합니다. 읽는 사람들이 이 내용이 없을 때는 보통 해당내용에 대한 생각을 먼저 떠올리지 않습니다. 사람들은 운영 중에 문제가 발생했을 때 이문서로 다시 돌아와서는 신나게 까내리게 됩니다. 빌미를 제공하지 않도록 미리 방어 합시다.
다른 팀에 영향을 주는 부분
- dev-ops팀에 어떤 영향을 주나요?
- 해당 솔루션이 발생시키는 추가 비용은 얼마인가요?
- 보안 취약점이 노출되나요?
- 부작용은 어떤 것이 있을수 있나요?
- 서비스 운영팀이 해당 개발사항을 고객에게 어떻게 전달해야하나요?
열린 질문
확실 하지 않은 미해결 사항, 독자가 고민 해줬으면 하는 부분, 논의가 필요한 사항들을 적습니다.
상세 타임라인
해당 섹션은 프로젝트에서 작업하는 엔지니어, 기술 책임자, 기술 관리자에게 알리는 내용 입니다. 보통 문서의 마지막에 위치합니다.
3. 작성 방법
1번 섹션 에서는 좋은 설계문서에는 어떤 내용이 담기는지에 대해 알아 보았고, 이제는 스타일에 대해 이야기 하려합니다. 고등학교의 영작 수업과는 다를 것을 약속합니다.
가능한 간단하게!
학술 논문처럼 작성하려 하면 안됩니다. 학술 논문은 논문 심사관에게 깊은 인상을 주기 위해 작성합니다. 설계문서는 솔루션을 팀원들에게 이해시키고, 피드백을 받기 위해 작성됨을 잊지 말아야합니다. 다음 문장 스타일링으로 내용의 명확성을 높일 수 있습니다.
- 간단한 단어.
- 짧은 문장.
- 불릿 목록/번호 목록.
- 구체적인 예제.
많은 차트와 다이어그램!
차트는 여러 잠재적 옵션을 비교하는 데 유용 할 수 있으며, 일반적으로 다이어그램은 텍스트보다 구문 분석하기 쉽습니다. 다이어그램 작성에는 구글 드로잉 앱이 최고였습니다.
PRO TIP: 다이어그램 이미지 아래에 편집 가능한 다이어그램 링크를 같이 첨부 합니다. 그래야 다이어그램 변경시 업데이트가 쉽습니다.
숫자 포함
검토자가 상태를 파악할 수 있도록 DB 행 수, 사용자 오류 수, 지연 시간과 같은 실제 숫자, 사용량에 따라 늘어나는 시간 복잡도(Big-O)를 넣어 표현 하세요.
웃기려는 노력
다시한번 말하지만 학술 논문이 아닙니다. 독자가 읽을 때 집중력을 높일 수 있도록 하는 좋은 스타일링 입니다. 문제 핵심을 벗어나게 할정도로 과도하게 사용하는 것은 금물입니다.
저처럼 재미없게 작성하는 사람들을 위해 조엘은 이런 팁을 제안 했습니다.
재미있게 작성하는 가장 쉬운 방법은, 예시를 작성할때 "사용자가..." 대신 "왼손잡이 아보카도 농부가..." 와 같이 쓸데없는 주변 정보를 넣는 것 입니다.
읽으면서 상상력을 불러 일으 키도록 합니다.
리뷰어 빙의 테스트
다른 사람에게 문서 리뷰 요청하기전에 본인이 리뷰어로 빙의 하여 한번 검토해보세요. 발견되는 문제들이 있을 수 있습니다.
휴가 테스트
지금 이 문서를 작성하고 휴가를 떠나더라도 팀원이 문서를 읽고 의도 한대로 구현 할 수 있나요? 이 테스트를 통과 해야합니다.
4. 프로세스
네 이제 대망의 마지막 단원인 프로세스 입니다. 설계문서는 잘못된 솔루션에 대한 구현을 진행하기 전 피드백을 받는데 도움이 됩니다. 좋은 피드백을 받는 방법에 대해서는 이후 포스트에서 작성 하겠습니다. 지금은 작성 프로세스와 피드백 프로세스에 대해 구체적인 설명을 하도록 하겠습니다.
첫째, 모든 작업 참여자는 설계 프로세스에 모두 참여해야 합니다. 모든 작업 참여자들이 토론에 참여하고 설계 내용에 대해 동의 해야합니다.
둘째, 설계 프로세스의 시작인 아이데이션은 단순히 노트에 아이디어를 끄적이는 것으로 는 충분하지 않습니다. 직접 솔루션의 프로토타입을 만들어 보세요. 솔루션의 구현용
코드를 작성 하는것이 아닙니다. 아이디어의 유효성을 검사하기 위한 목적으로 일회성 코드를 작성하고 실행시켜 유효성을 검증 합니다. 해당 프로토 타입코드가 develop/master 브랜치에 머지되지 않도록 규칙을 만들 필요가 있습니다.
이후, 솔루션의 실마리를 찾았다면 아래를 수행 하면됩니다.
- 숙련된 엔지니어 혹은 기술 책임자에게 리뷰어가 되도록 미리 요청 해둡니다. 문제에 대한 인지가 되어있는 사람들이 좋습니다. 버블티를 뇌물로 주고 매수합니다.
- 화이트 보드가 있는 회의실로 이동합니다
- 매수한 엔지니어에게 문제를 설명하세요.
- 생각하고 있는 솔루션을 설명하고 설득해 봅니다.
디자인 문서를 작성하기전에 위 작업을 수행하면, 문서작성에 더 많은 시간이 투자되기전에 피드백을 더빠르게 받을 수 있습니다. 솔루션이 동일하게 유지 되더라도 리뷰어는 다루어야 할 코너 케이스를 지적하고, 나중에 발생할 수있는 어려움을 예상 할 수 있습니다.
그런 다음, 설계문서의 초안을 작성하고 위 검토자가 다시 읽어보게 합니다. 그리고 제목및사람 섹션에 리뷰어를 추가 해 놓습니다. 이는 리뷰어에게 책임을 부여 합니다.
작성자와 리뷰어가 승인한 후, 피드백 및 지식 공유를 위해 팀 구성원 전체에 공유합니다. 검토 지연을 방지하기 위해 검토 일정을 1주로 제한 하는 것이 좋습니다. 사람들이 1주내에 남기는 모든 질문과 의견을 다룰 것을 같이 약속 합니다.
마지막으로, 피드백 주간에 있었던 논쟁이 있다면, 논쟁의 요점을 토론 섹션에 추가합니다. 이후, 논쟁에 참여했던 사람들과 회의를 설정 하여, 집중적인 논쟁을 하고 결론을 도출합니다.
토론 스레드의 댓글 길이가 5개 이상일때 회의를 통한 논쟁으로 이동하는 것이 효율적입니다. 모든 사람들이 동의 할 수 없는 상황이더라도 최종 결정은 작성자가 합니다.
이에 대해 최근 Shrey Banga 와 대화 하면서 Quip이 유사한 프로세스를 가지고 있다는 것을 알게되었습니다. 단, 숙련 된 엔지니어 또는 기술 책임자가 팀에 리뷰어인 것 외에도 다른 팀 의 엔지니어 가 문서를 검토하도록 제안 합니다. 실행 해본적은 없지만, 이것이 다른 관점을 가진 사람들로부터 피드백을 얻고 문서의 일반적인 가독성을 향상시키는 데 도움이되는 것을 확실히 볼 수 있습니다.
위의 모든 작업을 완료 했으면 구현을 시작할 시간입니다! 설계 사항을 구현할때 이 디자인 문서를 살아있는 문서로 취급하세요. 원래 솔루션을 변경하거나 범위를 업데이트하는 데 도움이되는 내용을 배울 때마다 문서를 업데이트 하세요.
마지막으로, 디자인 문서의 성공 여부를 어떻게 평가할까요?
Kent Rakip 이 이에 대한 좋은 답변을 준비해주었습니다. ROI가 충족되면 설계 문서는 성공적입니다. 성공적인 디자인 문서는 다음과 같은 결과를 도출 할 수도 있습니다.
- 디자인 문서를 작성하는 데 5 일이 소요되므로 기술 아키텍처의 여러 부분을 생각해야합니다.
- 리뷰어로부터, 제안된 아키텍처에서 가장 위험한 부분인 X에 대해 피드백을 받습니다.
- 프로젝트의 위험을 줄이기 위해 X에 대해 제일 먼저 구현하기로 결정했습니다.
- 3 일후, X가 불가능 하거나 원래 의도했던 것보다 훨씬 더 어렵다는 것을 알게됩니다.
- 프로젝트에 대한 작업을 중단하고 대신 다른 작업에 우선 순위를 부여하기로 결정했습니다.
위 결과 또한 디자인 문서의 목표인 올바른 작업을 수행하는 것을 만족 시킨 결과 입니다. 설계문서 덕분에 이 프로젝트를 실행하기 위해 1달을 낭비하는 대신 8일만 소비하고 종료 되었습니다. 성공적이라는 판단을 할 수 있습니다.
Top comments (1)
설계 문서는 단순한 형식적 문서가 아닌, 프로젝트의 성공을 위한 핵심 도구이군요.
도움이 되었습니다. 번역해주셔서 감사합니다!