프로덕트 스펙 문서 작성법
스펙 문서는 왜, 어떻게 써야 하는가?
원문: <On Writing Product Specs> by Gaurav Oberoi
서사적으로 구성된 6페이지 메모를 쓰고도 명확한 생각을 가지지 않을 수는 없다. — 제프 베조스
“스펙 문서”란 단어를 들으면 대부분은 인상을 찌푸린다. 아무도 읽지 않을 문서를 작성하는 데 보낸 시간을 생각하면서… 문서 작성까지 해야 한다면 누가 과연 민첩하게 코드를 쏟아낼 수 있겠는가? 수백만의 사람들이 사용하는 소프트웨어 프로덕트를 만들며 10년 넘는 시간을 보낸 후, 난 기존의 이런 생각이 잘못되었다는 것을 깨달았다.
효과적인 스펙 문서는 훌륭한 소프트웨어를 만드는 과정에서 결정적인 역할을 한다. 그러한 문서는, 개발 초기부터 비판적 사고를 하게끔 하고, 커뮤니케이션을 효율화하며 , 책임 소재를 분명히 함으로써 높은 품질, 일정 리스크 축소, 시간 낭비 최소화에 기여한다.
사례와 함께 관련된 일반적인 조언을 적어놓았다. 이 포스팅은 200명 정도 되는 mid-to-large 사이즈 기업의 프로덕트 매니저에게 가장 도움이 될 것이다.
사례
프로젝트 배경
당신은 지금 여행 예약 사이트를 운영하는 회사에 다니고 있다. hotels.com이나 airbnb.com과 유사하지만, 더 작다고 보면 된다. 결제 전환율이 낮은 상태이며, 이를 개선하기 위해서 이번 분기에 당신의 팀에서는 결제 페이지 라이브 채팅 도입을 시도해보기로 했다.
로드맵에 적혀진 프로젝트 설명
전환율 제고를 위한 결제 페이지 라이브 채팅 시범적 도입
현재 결제 전환율은 18%에 불과하다 (동종업계 평균은 30%). 이 수치 개선을 위해 결제 페이지에서 라이브 채팅 화면을 고객에게 노출해보기로 했다. 운영팀 담당자는 이 업무를 전담할 수 있는 담당자 1명을 배치해줬다.
당신이 스펙 문서 작성 없이 실행한다면..
이 업무가 최우선순위라고 생각해서 바로 뛰어들었다고 가정해보자.
1. 스프린트 기획 미팅에서 이 이슈에 관련해 팀에게 얘기를 꺼낸다.
2. 그리고, 바로 적당한 채팅 서비스 제공자(SnapEngage 같은)를 고른다.
3. 개발자에게 자바스크립트 코드를 좀 넣어달라고 티켓 내용을 업데이트한다.
4. 운영 준비상태를 확인하기 위해 고객 지원팀과 미팅을 가진다.
짠! 이렇게 간단한 일에 도대체 스펙 문서 나부랭이는 왜 필요한 거지? 당신이 작은 스타트업에서 일하고 있는 것이라면 꼭 필요한 건 아니다. 프로덕트에서 바뀌고 있는 부분도 적고, 관련된 사람 수도 적으니까. 하지만 당신이 더 큰 조직에서 일하고 있거나, 더 복잡한 프로덕트를 갖고 있다면 어떤 세부사항은 나중에 나타날지도 모르고, 그런 것들을 늦은 시점에 결정하면 더 큰 비용을 불러오기 마련이다.
어떤 상황이 올 수 있는지를 보자.
개발자가 티켓을 ‘완료' 상태로 변경했다. 시험 삼아 한번 실행해보자마자 당신은 이 기능이 모바일에서 작동하지 않는 것을 발견했다. → 헉! 모바일이 핵심이란 것을 깜빡하고 말하지 않았다.
운영팀 담당자가 ‘적절한 채팅 툴을 골랐는가’에 관련해서 심각한 미팅을 요청했다. → 윽.. 이건 테스트일 뿐이라는 것을 설명하기 위한 미팅을 잡는다.
서비스 개시 1시간 후, 지원 담당자가 스페인어로 된 채팅 요청을 계속 받고 있다고 말한다. → 이크! 지원 언어를 영어로 한정하기 위한 긴급 패치를 진행한다.
디자이너가 완벽한 슬라이드인 애니메이션으로 라이브 채팅 화면을 불러오기 위해 며칠씩 공을 들이고 있다. → UX gold-plating(금도금)이다. 이건 테스트일 뿐이라고 기대수준을 맞췄던가?
테스트 시작 1주일 후, BI 담당자가 적합한 지표가 기록되고 있지 않기 때문에 당신에게 필요한 레포트를 만들 수 없다고 말한다. → Epic fail. 테스트를 다시 시작한다.
스펙 문서가 없다고 이런 재앙이 꼭 닥치리라는 법은 없다(이건 비교적 작은 프로젝트이니까). 그러나 아마 당신은 시간을 낭비하거나, 중요한 부분을 놓칠 것이다.
그래서, 당신은 스펙 문서를 쓰기로 했다.
설명을 위해 초기 단계의 노트와 완성된 단계의 스펙 문서 예시를 제공한다. 예시를 읽고 돌아오길 권장한다.
초기 단계 노트 예시 (2분 분량)
지금 알고 있는 정보와 답하고 싶은 질문들을 불릿 포인트로 적은 것이다. 혼자서 먼저 적어보자(예상 소요시간: 1 시간). 이 문서가 당신이 팀 구성원과 다른 관계자들과 논의를 진행하기 위한 기본 자료가 될 것이다.
스펙 문서 예시 (6분 분량)
초기 노트로 당신의 가정과 아이디어를 팀 구성과 확인한 다음에야 확신을 두고 스펙 문서 작성에 들어갈 수 있다(예상 소요시간: 1–3 시간).
아직 확신이 들지 않는가? 스펙 문서 작성이 쓸데없는 추가 업무 같아 보일지도 모르지만, 그렇지 않다. 효과적인 스펙 문서는 당신과 팀의 시간을 절약해주고, 프로덕트를 자신있게 출시할 수 있도록 도와준다.
잠깐! 위의 예시를 아직 읽지 않았는가? 그렇다면 먼저 읽고 오기를 권장한다.
“엔지니어링 업무에서, 문서로 커뮤니케이션하는 것이 구두로 하는 것보다 더 낫다. 일관성, 지속성이 있으며 책임 소재를 분명히 하기 때문이다” — 벤 호로비츠스펙 문서 쓰는 법
이 포스팅의 나머지 부분에서 제시하고 있는 아이디어가 와 닿게 하기 위해 예시 문서를 작성했다. 아래로 넘어가기 전에 스펙 문서 예시를 먼저 읽기를 바란다.
왜 스펙 문서를 쓰는가?
적합한 프로덕트를 더 높은 품질로, 빠르고, 예측할 수 있게 내놓기 위해서.
어떻게 스펙 문서가 그걸 가능하게 하는가? 벤 호로비츠의 말과 스펙 문서 예시를 통해 ‘왜' 에 대해서는 설명했지만 확실하기 위해 더 적어보았다.
1. 초기부터 비판적 사고를 하게끔 한다.
글을 쓰는 것은, 설계, 코딩, 디자인, QA 등의 ‘비싼 작업'이 시작되기 전에 먼저 구체적인 부분에 대해 생각하게 한다. 선택의 질을 높여주며, 생각하지 못한 돌발 상황이 생길 확률도 줄여준다.
2. 커뮤니케이션을 효율적으로 할 수 있게 한다.
어떤 방식으로든, 당신은 다양한 관계자들(운영, 개발, 디자인, 재무, 경영진 등)과 이 계획에 대해 커뮤니케이션하게 될 것이다. 스펙 문서는 이러한 커뮤니케이션을 묶어서 해결할 수 있게 해주고(이런 문서 없이 구두로 설명한다면 각자가 이해하는 바가 모두 달라질지도 모른다), 모호한 부분이 없게 함으로써 다른 사람들이 이해하고, 지적인 응답을 할 수 있게 해준다.
3. 책임 소재를 분명히 한다.
측정 가능한 목표를 공개적으로 알림으로써 팀의 목표를 정렬해주는 효과가 있다. 관계자들은 마지막 순간에 추가 요청하는 것이 얼마나 무리한 일인지 알게 될 것이고, 개발자들은 일정을 산정할 때 숙고하게 될 것이다.
스펙 문서에 무엇이 포함되어야 하는가?
스펙 문서는 무엇을, 왜 만들어야 하는지에 대한 명확한 결정사항을 모아놓은 문서이다. 아이디어를 구조화하는 방법은 여러 가지가 있지만, 핵심 내용은 다음 다섯 가지다.
문제(The Problem)
풀고 싶은 문제를 정리하라. 중요한 것은, 이게 왜 다뤄져야 하는지를 설명하는 것이다. 구체적으로 설명하고 지표를 제공하라.
측정 가능한 목표(Measurable Goals)
결과물을 명시하라. 무엇이 범위에서 제외되는지도 밝혀라. 목표를 보고 “우리가 이걸 달성했나?” 라는 질문에 답변할 수 있도록 목표를 세워야 한다.
상황(Context)
문제에 대해 이해하고 당신의 제안 사항에 동의할 수 있게끔 하는 근거를 제공하라. 가정, 사례, 지표 등..
상세한 해결방안(Detailed Solution)
팀에서 보고 실행할 수 있을 정도로 자세하게 적어야 한다. 실제 작업에 참여할 사람들의 두뇌를 가동하게 하는 코드를 작성한다고 생각하라.
일정(Timeline)
팀에서 논의된 날짜별 마일스톤을 적어라. 처음엔 대략 적더라도, 마지막 리뷰미팅 전에 최종적으로 결정되어야 한다.
위에 첨부한 예시를 템플릿으로 활용해보는 것도 괜찮다. 필요하다면 섹션을 추가/삭제/이동하라. 위의 5가지 포인트가 명확하고 서사적인 구조를 유지한다면 어떻게 되어도 괜찮다.
스펙 문서는 어떻게 쓰는가?
다음은 내가 스펙 문서를 작성하고 리뷰하는 과정이다. 프로젝트의 사이즈나 관련된 사람들의 수에 따라 달라질 수 있지만, 일반적으로 이렇게 진행된다.
초안을 작성한다 (1–2시간)
Slack과 이메일을 닫는다. 차나 커피를 가져온다. 의자에 기대앉아 생각 한다. 그리고 알고 있는 것들을 불릿 형식으로 적어나간다(예시 참고).
두어 번의 30분짜리 1:1 미팅을 잡는다 (1–4시간)
이 작업의 목표는 가정을 만들어 나가고, 제안을 개선하며, 사람들을 끌어들이는 데에 있다. 이 미팅이 거창해지지 않도록 최대한 적은 사람이 집중해 참여하게 하라(1:1 미팅이 이상적이다). 예를 들면, 이 경우에는 고객 지원 담당자, 재무 담당자, 그리고 개발자와 각각 1:1 미팅을 잡을 것이다.
스펙 문서를 작성하고 수정한다 (0.5–3일)
이 시점에서 당신은 이제 무엇을 할 수 있고, 또 해야 하는지에 대해서는 확실한 아이디어를 가지고 있을 것이나, 여러 상세한 항목들은 머릿속을 어지럽게 돌아다니고 있을 것이다. 비판적인 사고와 글쓰기로 이것들을 정리해보아라. 초안 작성을 마치고 나서는, 계속 수정해라. 보통 초안을 기준으로 30–50% 짧아지도록 할 수 있으며, 그렇게 해볼 가치가 있다. 간결성과 명확성을 높임으로써 사람들이 더 읽게 할 수 있으므로. 대부분의 스펙 문서는 0.5–1일 안에 쓸 수 있지만, 더 규모가 있는 프로젝트의 문서 작성에는 2–3일이 걸리기도 한다.
문서를 보내고 1시간짜리 리뷰 미팅을 잡아라 (15분)
직접 관계된 사람들을 “to”에 넣고, 관련이 있을 수 있는 사람들(product team 사람들, 더 넓은 범위의 운영 조직 등)을 “cc”에 넣어서 메일을 보내라. 중요인물들을 미팅에 초대하라. 의사 결정에 거부/동의 권한이 있거나, 직접 프로젝트에 참여하는 사람들을 말한다.
스펙 리뷰 미팅 (1시간)
스펙 문서를 자세히 읽지 않은 사람이 있는지 물어보면서 시작하라. 한두 명이 이에 해당할 것이다. 그 경우 “걱정하지 마세요, 다 같이 10분 동안 읽고 시작하죠. 다 읽으셨다면 잠깐 쉬고 계셔도 좋습니다.” 라고 말하고, 다 같이 읽는 시간을 가지도록 하라. 이 미팅을 통해 관계자들의 동의를 구하고, 직접 실행할 사람들(개발, 운영)에게는 책임을 확인하라. 이 과정에서 알게 된 것을 토대로 문서를 업데이트하고, 미팅을 다시 가져야 할 수도 있다.
리뷰 미팅 후, 업데이트된 내용을 보내고, 티켓을 만들어라 (1–2시간)
이 이메일에는 업데이트된 스펙 문서와 프로젝트와 관련된 티켓들의 링크(티켓들은 작업 단위로 쪼개진다 — 자바스크립트 코드 추가, BI 레포트 작성, 스테이징 서버에서 테스트, 운영팀과 함께 예행연습 등..), 그리고 언제 다음 메일을 보낼지에 대한 대략적인 언급이 있어야 한다. 종종 다음 단계는 개발자가 기술 스펙을 작성하는 것이지만, 항상 필요한 것은 아니다 (이 예시처럼 간단한 경우에는 필요하지 않다).
효과적인 스펙 문서에 관한 팁
짧게 써라
이보다 더 중요한 팁은 없다. 간결성은 사고와 커뮤니케이션에서의 명확성을 불러온다. 또한, 사람들은 짧은 문서를 더 잘 읽고 이해한다. 이게 가장 중요하다.
명백한 어휘와 단순한 포맷을 사용하라
미사여구보다는 짧고 간결한 어휘를 사용하라. 불릿과 볼드를 이용해 문서를 훑어보기 편하게 만들어라. 너무 딱딱하지 않게 쓰고, 재미있게 써라. 자신이 있다면 유머를 덧붙여도 좋다.
(개발팀 일정에) 앞서서 써라
완성된 스펙 문서는 이미 검토 과정을 마치고 모두의 동의를 구한 상태여야 한다. 즉, 스프린트가 시작하기 2–3주 전에는 이 작업을 시작해야 한다.
개발자처럼 생각하라
보통은 실제 개발자가 코드를 작성할 때가 되어서야 특이 케이스들이 나타나지만, 항상 그러란 법은 없다. 어떻게 만들지를 미리 깊게 생각한다면 그런 부분을 미리 정하여 언급할 수 있다(e.g., 라이브 채팅이 모바일에서 돌아가는가?).
모두를 동참시켜라
내 프로젝트의 스펙 리뷰 미팅을 진행할 때면, 이미 대부분의 사람은 이게 어떤 것인지를 알고 있다. 내가 작은 미팅이나 비공식적인 대화/채팅을 통해서 미리 전달했기 때문이다. 이런 방법으로 ‘무엇을 왜 하는지'에 대한 커뮤니케이션을 미리 마친 상태에서 본격적으로 디테일에 집중할 수 있다.
시각화에 대해 열심히 고민하라
플로우 다이어그램이나 와이어프레임 같은 시각화는 중요하다. 많은 양의 정보를 쉽게 이해하도록 도와준다. 물론 이건 많은 시간이 필요하다.
생각하고 쓰는 데에는 0.5–3일만 써라
이것보다 더 많은 시간을 들이는 것은 더 못한 결과를 가져오는 경우가 많다. 아무도 5–6페이지보다 긴 문서를 읽지 않을 것이기 때문에.
방향과 비전을 제시하라
단지 이 기능을 정의하는 데서 끝낼 것이 아니라, 왜 이것을 해야 하는지와, 앞으로 어떤 방향으로 갈 것인지에 대해서도 전달해야 한다. 거시적인 관점에서 이 프로젝트를 보게 하고, 다음엔 어떤 일을 진행할 것인지도 언급해주면 좋다.
읽히도록 만들어라
스펙 문서가 길거나, 정신없거나, 적절한 대상에게 공유가 되지 않았다면 당신은 문서를 쓰지 않은 것이나 다름없다. 읽히도록 만들어라. 리뷰 미팅을 시작할 때 다 같이 읽는 시간을 만드는 것도 좋다.
솔직한 피드백을 받아라
명백하게 썼는가? 아니면 정보가 불충분한가? 나중 단계에서 특이 케이스를 잔뜩 발견할 것 같은가? 기획/검토 단계에서 너무 많은 시간을 들이고 있는가? 팀에게 물어봐라.
—
역자 주
Product spec은 제품 명세(서) 등으로 번역되기도 한다. 예시 문서를 보면 알겠지만, 명세서 느낌은 아니라서.. 스펙 문서라고 번역했다.
초기 단계 노트 예시와 스펙 문서 예시에서는 각 섹션 타이틀을 원문 그대로 두었다. 회사에서 사용하고 있는 용어에 따라 적절하게 번역해서 사용하시면 될 것 같다.
