자신의 할일(하는 업무) 구조화 하기

“내용을 구조화(서술적인 메모)하고 6p 이내로 정리하면 명확한 방향(생각)을 가질 수 있다.” — 제프 베조스

Most people groan when they hear “product spec”. They think of weeks spent writing docs that no one reads. How can one be agile, and pumping out code like a rockstar, if one is encumbered with documentation? After having spent over a decade building software products used by millions of people, I think this view is misguided. In my experience:

“많은 사람들이 제품 스펙”이라는 단어를 들으면 대부분은 인상을 찌푸린다. 그들은 아무도 읽지 않을 문서를 작성하는 데 수주간의 시간을 생각하고 허비 하는데… 문서 작성까지 해야 한다면 누가 과연 민첩하게 Rockstar록스타 같은 멋진 코드를 쏟아낼 수 있겠는가? 수백만의 사람들이 사용하는 소프트웨어 제품(서비스)를 만들며 10년 넘는 시간을 보낸 후, 난 기존의 이런 생각이 잘못되었다는 것을 깨달았다.

Effective product specs are a critical part of building great software. They force critical thinking up front, scale communication, and raise accountability — all leading to higher quality, lower schedule risk, and less wasted time.

효과적인 제품 스펙(문서)는 훌륭한 소프트웨어를 만드는 과정에서 결정적인 역할을 한다. 그러한 문서는, 개발 초기부터 비판적 사고를 하게끔 하고, 커뮤니케이션을 효율화하며 , 책임 소재를 분명히 함으로써 높은 품질, 일정 리스크 축소, 시간 낭비 최소화에 기여한다.

In this post I’ll walk through an example, and share some general advice. This will be most useful for product managers in mid-to-large companies (100+ people).

사례와 함께 관련된 일반적인 조언을 적어놓았다. 이 포스팅은 100명 정도 되는 중소/대 기업의 프로덕트 매니저에게 가장 도움이 될 것이다.

1^st an Example

Suppose you work at:

A company that runs a vacation booking site (like Hotels.com or AirBnb.com but smaller). Your checkout conversion is low, and one idea the team wants to try this quarter is live chat during checkout.

사례 : 여행 예약 사이트를 운영하는 회사에 다니고 있다. hotels.com이나 airbnb.com과 유사하지만, 더 작다고 보면 된다. 결제 전환율이 낮은 상태이며, 이를 개선하기 위해서 이번 분기에 당신의 팀에서는 결제 페이지 라이브 채팅 도입을 시도해보기로 했다.

Your story & roadmap says:

Try adding live chat to checkout to increase conversion.
Checkout conversion is only 18%, whereas the industry standard is 30%. Let’s test showing customers live chat during checkout to see if we can improve it. Customer ops has agreed to lend us 1 head for a month.

전환율 제고를 위한 결제 페이지 라이브 채팅 시범적 도입
현재 결제 전환율은 18%에 불과하다 (동종업계 평균은 30%). 이 수치 개선을 위해 결제 페이지에서 라이브 채팅 화면을 고객에게 노출해보기로 했다. 운영팀 담당자는 이 업무를 전담할 수 있는 담당자 1명을 배치 했다.

And you execute without a spec:

Let’s say you decide that action is 1^st priority, and jump into it:

1. You chat about this with your team in the sprint planning meeting.
2. Then you simply pick a reasonable chat service (like Slack).
3. Update the ticket to ask a developer to slap in some Javascript.

And have a meeting with Support to make sure they’re all set.

당신이 스펙 문서 없이 실행한다면….
이 업무가 최우선 순위라고 생각해서 바로 시작한다고 가정해보자.

1. 스프린트 기획 미팅에서 이 이슈에 관련해 팀에게 얘기를 꺼낸다.
2. 그리고, 바로 적당한 서비스 제공자 (Slack 같은)를 고른다.
3. 개발자에게 자바스크립트 코드를 좀 넣어달라고 티켓 내용을 업데이트한다.
4. 운영 준비상태를 확인하기 위해 고객 지원팀과 미팅을 가진다.

Boom! Why do we need all that spec fuss anyways? Well if you’re a small startup, you don’t — because there are fewer moving parts, and fewer people involved. But if you’re in a larger org, or have a more mature/complex product, the details will appear at some point, and they’ll cost more to address later. For instance:

짠! 이렇게 간단한 일에 도대체 스펙 문서 나부랭이는 왜 필요한 거지? 당신이 작은 스타트업에서 일하고 있는 것이라면 꼭 필요한 건 아니다. 프로덕트에서 바뀌고 있는 부분도 적고, 관련된 사람 수도 적으니까. 하지만 당신이 더 큰 조직에서 일하고 있거나, 더 복잡한 프로덕트를 갖고 있다면 어떤 세부사항은 나중에 나타날지도 모르고, 그런 것들을 늦은 시점에 결정하면 더 큰 비용을 불러오기 마련이다

• A dev marks the ticket as done, but on giving it a spin, you realize it doesn’t work on mobile. →Doh! You forgot to mention that mobile is key.
• The customer ops manager wants to have a lengthy vendor review to pick the right chat tool. → Schedule a meeting to explain this is only a test.
• An hour after launch, support says they are getting live chat requests in Spanish. →Yikes! Do an emergency release to limit to English only.
• A designer spends days crafting the perfect slide-in animation to display live chat. →UX gold-plating. Did you set expectations that this is a test?
• After a week of testing, BI realizes they can’t build the report you need because the right metrics weren’t logged. →Epic fail. Restart the test.

Without a spec, you might not have a disaster on your hands (this is a relatively simple project), but you will likely waste time and opportunity.

어떤 상황이 올 수 있는지를 본다면,

• 개발자가 ticket을 ‘완료’ 상태로 변경했다. 시험 삼아 한번 실행해보자마자 당신은 이 기능이 모바일에서 작동하지 않는 것을 발견했다. →헉! 모바일이 핵심이란 것을 깜빡하고 말하지 않았다.
• 운영팀 담당자가 ‘적절한 채팅 툴을 골랐는가’에 관련해서 심각한 미팅을 요청했다. →윽.. 이건 테스트일 뿐이라는 것을 설명하기 위한 미팅을 잡는다.
• 서비스 개시 1시간 후, 지원 담당자가 스페인어로 된 채팅 요청을 계속 받고 있다고 말한다. → 이크! 지원 언어를 영어로 한정하기 위한 긴급 패치를 진행한다.
• 디자이너가 완벽한 슬라이드인 애니메이션으로 라이브 채팅 화면을 불러오기 위해 며칠씩 공을 들이고 있다. →  이건 테스트일 뿐이라고 기대수준을 맞췄던가?
• 테스트 시작 1주일 후, BI 담당자가 적합한 지표가 기록되고 있지 않기 때문에 당신에게 필요한 레포트를 만들 수 없다고 말한다. → Epic fail. 테스트를 다시 시작한다.

스펙 문서가 없다고 이런 재앙이 꼭 닥치리라는 법은 없다(이건 비교적 작은 프로젝트이니까). 그러나 아마 당신은 시간을 낭비하거나, 중요한 부분을 놓칠수 있다.

Now suppose that you wrote a spec:

To illustrate, I’ve written up what early notes might look like, as well as a completed example spec — so you can see what the evolution might look like. Take a few minutes to go and read these before coming back.

• Read example notes. (2 min read)
  This is a bulleted brain dump of what you know, and questions you want to answer. Write this up front by yourself. It should take about an hour. This is your straw-man to vet with your team and stakeholders.

그래서, 당신은 스펙 문서를 쓰기로 했다.

설명을 위해 초기 단계의 노트와 완성된 단계의 스펙 문서 예시를 제공한다. 예시를 읽고 시작하길 권장한다.

• 초기 단계 노트 예시(2분 분량)
  지금 알고 있는 정보와 답하고 싶은 질문들을 불릿 포인트로 적은 것이다. 혼자서 먼저 적어보자(예상 소요시간: 1 시간). 이 문서가 당신이 팀 구성원과 다른 관계자들과 논의를 진행하기 위한 기본 자료가 될 것이다.

This is an example early draft product spec/notes, written as part of this post.

Problem:

• Conversion sucks. 18% but should be able to do 30% (need source).
• What else have we tried here, and why is this worth trying? Need to look up our past support case summary and survey results.

Goals

• Prove live chat is worth it. Be ok with scrapping if the results stink.
• Ideally have an answer by start of Dec so we can ask for support resources in Q1.

Chat vendor?

• Look at the top few and pick one: slack, etc.
• What does the UX look like and how much customization is needed and possible?
• We need cust ops to manage setting their hours, and agents, without a code push!
• What is the integration cost? Just drop in a Javascript snippet, or…?
• How much reporting do we get from the tool vs. what do we need to build in house?
• Can we pass in some variables for our own custom reporting? Like user_id?
• Can we ignore integrating with our support ticketing ZenDesk instance right now?

Success criteria:

• Need to model out cost of one chat person, vs. how many chats they can do vs. how many new conversions those chats can bring.
• If we can’t make this work in Excel, no point in trying the test.
• Must get early feedback from cust ops manager and finance.

Running the test

• How much traffic to send? It’s a function of: number of people who click to chat, average time per chat, number of simultaneous chats we’ll allow, wait time, etc.
• We can model this, but it’s not worth it given we have no data and lots of assumptions.
• Instead, let’s roll with a guess, like 20% of traffic, and slowly dial up a knob till we know.
• How many days do we need to run this? Do we need to worry about traffic seasonality?

What reports do we need?

• I want to know conversion, revenue, and total orders in the test and control.
• Also how many people in the test actually engaged (initiated a chat).

Anything else?

• What about international? I’d say skip it for now.
• Mobile? Fer sure. 30% are checking out on their phones.
• Page load times? Make sure this chat widget doesn’t slow down the page!

---

Example of notes you might take to get the process started.

• Read the example spec. (6 mins)
  You’ll only feel confident writing this after vetting your assumptions and ideas by your team (in small focused meetings, over coffee, or on a foosball break). Once that’s done, this spec should take 1–3 hours.

• 스펙 문서 예시 (6분 분량)
  초기 노트로 당신의 가정과 아이디어를 팀 구성과 확인한 다음에 좀더 확신을 가지고 작성에 들어갈 수 있다(예상 소요시간: 1–3 시간).

This is an example product spec, written as part of this . Some notes:

• Commentary will appear with this light blue background throughout the doc.
• Read the doc once through while ignoring the blue bits, then go back and reread.
• Links don’t go anywhere. They exist to illustrate the need to do and show related work.

Live chat on checkout

This project aims to increase conversion by introducing live chat on our checkout page. It is a 30-day experiment, after which we’ll keep it alive or kill it ( chat?).

Describe the project in 2 lines or less. By “line” I mean the default reading width of your medium (e.g., Google Docs, wiki, text file) on a desktop client. Sticking to limits is critical for readability.

Overview

Problem

1. Checkout conversion is too low: only 18% of users who click on “Book” checkout. Comparable funnels for hotel booking sites achieve ~30% (source). We are missing out!
2. No clear dropout reason: prior support tickets and survey results show a long tail of possible issues (questions on amenities, fees, checkout time), no clear categories.
3. Adding help content didn’t do much: last quarter we A/B tested content and UI to better point to help content and booking info. This nudged conversion by 1.5% points.

I highly recommend bullets for readability. Use bold words to quickly convey the gist of each point, and limit bullets to 2-3 lines. I prefer numbered lists so one can refer to a point verbally.

Goals

1. Test if live chat can profitably increase conversion: we need to add 90+ orders/day just to break even on our live chat support cost. Unclear if we can do it. This is a test!
2. Keep the test cheap: avoid all gold-plating, this will come in Q1 if our test succeeds.
3. Get final answer by Dec 1: we have 8 weeks before Q1 resource planning starts.

Make sure one can point to a goal and easily answer “did we hit it?”. Make clear promises.

Out of Scope

1. Major UX changes: we will only add a visible chat button, no other UX changes.
2. Finalizing a chat vendor: we’ll use slack for now, and review if the test works.
3. International and non-English: only US/English users to keep our test simple.

This is your chance to eliminate bad assumptions and correctly set expectations.

People and Roles

1. Heather (cust ops manager): sign off on our support resourcing assumptions.
2. Kim (cust ops rep): man the queue, and summarize learnings once a week.
3. lyn (dev): build and qa. Also configure Slack, and show us all how you did it.
4. lee (finance): review my profitability assumptions for our test, and down the road.
5. Joshua (design): very light review of the changes we’ll make, no major design requests.
6. Viky (admin & dasbboard): make sure we can get the reporting we need in time for the test.

Help everyone know who is involved, and what is expected of them. Only include people who have authority to veto/approve decisions, or people who will execute on the plan.

Context

Use this section to provide supporting evidence for your problem and proposal. Add whatever you need here, e.g.: use-cases, personas, metrics, competitors’ solutions, survey results, etc.

Use Cases

1. Users want to:
   1. Get help within 2 mins: unsure if this is achievable, but let’s aim here for now.
   2. On mobile or desktop: 28% of checkouts are on the phone, so this is critical.
2. Customer Ops wants to:
   • . Be in the queue: via a desktop/web client, mobile is not needed.

1. Add/reduce agents: on their own without having to consult the dev team.
2. Set working hours: control when the live chat button is visible on the site.
3. View user info: we must pass in the user-id so they can look up the current user.
4. Tag chats: after a chat is done, put unstructured text into a comments field.

Assumptions

1. Need +90 orders/day to break even with 1 support head: based on cost per head, and lifetime value of a checkout. See spreadsheet for details.
2. Send 20% of checkout traffic per support head: based on some assumptions on wait times, chat lengths, and number of simultaneous chats. We don’t have any data to make a good guess, so let’s pick this and allow our system to ramp traffic up/down quickly.
3. Checkout conversion should go from 18% to 20%: total conversion won’t increase much for us to be successful. See our funnel report

Proposal

Describe your proposal in the most natural way you can. Break it up into sections, and give it a clear narrative flow. Depending on the project, you may also add: wireframes, user flow diagrams, form inputs/validations, data models… all the specifics needed to execute the plan.

Live Chat Vendor

I picked Slack, they meet our stated use-cases and are cheap ($60/month). Note: we’ll do a proper vendor selection if this works. I created a paid account, credentials in our pw tool.

User Experience

View the Slack docs to get an idea of how their chat pops up. Based on that:

1. Button: label it “Chat Now” and put it near our primary on the detail page.
2. Behavior: on click, show the agent’s name, and “How can we help you today?”.
3. All checkout pages: it should persist across all 3 steps of checkout.
4. No auto-popup: we may try this later, but let’s keep it low key for now.

Chat Variables

1. What is it: when we embed the vendor’s javascript, we can pass on additional variables that the support person can see, and will also get logged in reporting.
2. Let’s send: user_id, user_email, user_agent, booking_id, booking_order_value.

Knobs for Running the Test

We will only show this to some checkout page traffic. Here’s what we need to make that work:

1. Only show to X% users: we must be able to control X without a redeploy, but it’s ok if CS has to file a ticket to dev to do this manually (e.g. if it’s in our DB/Redius).
2. Persist which users see it: if a user sees live chat once, they should continue to see it on any given day that we’re running the test. Either cookie them, or base it on their user_id (e.g., show it if user id modulo 100 <= X).
3. Ramp up plan: on day 1, we’ll only have this be at 5%, but will go to 10% on day 2 and then 20% by day 3 if all is going well per customer ops.

Metrics and Reports

1. Logging: add: “live_checkout=true/false” to our existing metrics logging during checkout.
2. New reports:
   1. Conversion rate for users in live chat (test) vs. without it (control).
   2. Total num orders and revenue attributed to live chat.
   3. Of users in the test, how many actually click on live chat.
3. Slack reporting: can tell us time spent per chat, simultaneous chats, etc.

My example above may seem obtuse, but it won’t be for my engineering and BI teams — and that’s the audience it is for. Remember: write what is necessary for human brains to execute.

Future Work

1. If we see very little live chat usage: we’ll need to try a few things like: (a) auto pop-up chat, (b) change CTA copy/UI, (c) photo of agent next to chat CTA.
2. If the test succeeds: we’ll ask for more heads, and do a bigger roll out in Q1 with vendor selection, better reporting for wider consumption, and formal chat training.

It’s always a good idea to signal where this is headed so people can think longer-term.

Tasks and Timeline

This timeline may slip by 1-2 weeks due to the kinds of issues mentioned in “future work”. That’s ok as long as we have results by Dec 1, so we can ask for heads during Q1 resource planning.

1. Oct 4: spec review.
2. Oct 8: test on dev env with customer support’s help in setting up agents/times.
3. Oct 11: launch. We will need to increase traffic over the next few days.
4. Oct 17: sync after 1 week. We may have additional tasks then.
5. Nov 12: final sync to review stats and decide if we want to do more or kill it.
6. Dec 1: this is the hard date for having the project wrapped up and results on hand.

It’s ok if you only have a rough estimate, and need more analysis to refine it (such as a tech spec). But it’s still important to try and put time bounds down as early as possible to signal roughly the size and scope. Estimates must come from the builders (dev, design, etc.).

Example of a completed spec.

Aaah, doesn’t that feel more solid? Writing a spec may seem like extra work, but it’s not. Effective specs will help you and your team save time, and deliver with confidence.

아직 확신이 들지 않는가? 스펙 문서 작성이 쓸데없는 추가 업무 같아 보일지도 모르지만, 그렇지 않다. 효과적인 스펙 문서는 당신과 팀의 시간을 절약해주고, 프로덕트를 자신있게 출시할 수 있도록 도와준다.

STOP! —Have you read the example spec yet? Read it now, please.

“엔지니어링 업무에서, 문서로 커뮤니케이션하는 것이 구두로 하는 것보다 더 낫다.
일관성, 지속성이 있으며 책임 소재를 분명히 하기 때문이다” — 벤 호로비츠

A Guide to Writing Specs

I started with an example to anchor the ideas presented in the rest of this post. Do make sure you read the example spec before continuing.

Why write a spec?

To ship the right product with higher quality, speed, and predictability.

스펙 문서 쓰는 법

이 포스팅의 나머지 부분에서 제시하고 있는 아이디어가 와 닿게 하기 위해 예시 문서를 작성했다. 아래로 넘어가기 전에 예시 문서를 먼저 읽기를 바란다.

왜 스펙 문서를 쓰는가?

적합한 프로덕트를 더 높은 품질로, 빠르고, 예측할 수 있게 내놓기 위해서.

Yeah, that’s it. Now, how does a spec help you do that? Horowitz says it well above, and my example illustrates why, but here it is for clarity:

1. Do critical thinking up front
   Writing forces you to think through specifics, in prose, before the expensive work of architecture, coding, design, qa, etc. takes place. It raises the quality of your decisions, and reduces the chance of surprises.
2. Communicate efficiently
   One way or another, you will communicate your proposal to various stakeholders (support, engineering, design, finance, management, etc.). A spec allows you to batch this communication, and to do it without ambiguity so your team can grok and respond intelligently.
3. Raise accountability
   By publicly committing to measurable goals you align the incentives of the team: stakeholders will realize how unreasonable last minute requests are, and engineers will think twice when making estimates.

어떻게 스펙 문서가 그걸 가능하게 하는가? 벤 호로비츠의 말과 스펙 문서 예시를 통해 ‘왜’ 에 대해서는 설명했지만 확실하기 위해 더 적어보았다.

1. 초기부터 비판적 사고를 하게끔 한다.
   글을 쓰는 것은, 설계, 코딩, 디자인, QA 등의 ‘비싼 작업’이 시작되기 전에 먼저 구체적인 부분에 대해 생각하게 한다. 선택의 질을 높여주며, 생각하지 못한 돌발 상황이 생길 확률도 줄여준다.
2. 커뮤니케이션을 효율적으로 할 수 있게 한다.
   어떤 방식으로든, 당신은 다양한 관계자들(운영, 개발, 디자인, 재무, 경영진 등)과 이 계획에 대해 커뮤니케이션하게 될 것이다. 스펙 문서는 이러한 커뮤니케이션을 묶어서 해결할 수 있게 해주고(이런 문서 없이 구두로 설명한다면 각자가 이해하는 바가 모두 달라질지도 모른다), 모호한 부분이 없게 함으로써 다른 사람들이 이해하고, 지적인 응답을 할 수 있게 해준다.
3. 책임 소재를 분명히 한다.
   측정 가능한 목표를 공개적으로 알림으로써 팀의 목표를 정렬해주는 효과가 있다. 관계자들은 마지막 순간에 추가 요청하는 것이 얼마나 무리한 일인지 알게 될 것이고, 개발자들은 일정을 산정할 때 숙고하게 될 것이다.What should a spec contain?

Your spec is a clearly communicated decision on what to build, and why. There are many ways to express your ideas in a structured manner, but at the heart of it, you must address these five things:

1. The Problem
   Frame the problem that you trying to solve. More importantly, explain why it is worth addressing. Be specific, and provide metrics.
2. Measurable Goals
   Promise clear deliverable and outcomes. Identify what’s out of scope. Make sure it’s easy to look at each goal and answer: did we hit it?
3. Context
   Provide evidence that your audience needs to understand the problem and believe in your proposal. Assumptions, use-cases, metrics, etc.
4. Detailed Solution
   Your proposal should be detailed enough for your team to consume and execute — think of it like code for human brains to run[1].
5. Timeline
   List dates and milestones that your team believes in. This section may start off vague, but should be finalized in your last spec review.

Use the example spec above as a template for writing your own. Add/remove/move sections as you see fit, the narrative structure doesn’t matter as long as you address the above points in a clear and specific manner.

스펙 문서에 무엇이 포함되어야 하는가?

스펙 문서는 무엇을, 왜 만들어야 하는지에 대한 명확한 결정사항을 모아놓은 문서이다. 아이디어를 구조화하는 방법은 여러 가지가 있지만, 핵심 내용은 다음 다섯 가지다.

1. 문제(The Problem)
   풀고 싶은 문제를 정리. 중요한 것은, 이게 왜 다뤄져야 하는지를 설명하는 것이다. 구체적으로 설명하고 지표를 제공하라.
2. 측정 가능한 목표(Measurable Goals)
   결과물을 명시하라. 무엇이 범위에서 제외되는지도 밝혀라. 목표를 보고 “우리가 이걸 달성했나?” 라는 질문에 답변할 수 있도록 목표를 세워야 한다.
3. 상황(Context)
   문제에 대해 이해하고 당신의 제안 사항에 동의할 수 있게끔 하는 근거를 제공하라. 가정, 사례, 지표 등..
4. 상세한 해결방안(Detailed Solution)
   팀에서 보고 실행할 수 있을 정도로 자세하게 적어야 한다. 실제 작업에 참여할 사람들의 두뇌를 가동하게 하는 코드를 작성한다고 생각하라.
5. 일정(Timeline)
   팀에서 논의된 날짜별 마일스톤을 적어라. 처음엔 대략 적더라도, 마지막 리뷰미팅 전에 최종적으로 결정되어야 한다.

위에 첨부한 예시를 템플릿으로 활용해보는 것도 괜찮다. 필요하다면 섹션을 추가/삭제/이동하라. 위의 5가지 포인트가 명확하고 서사적인 구조를 유지한다면 어떻게 되어도 괜찮다.

How to write a spec?

Here’s the general process that I follow to write and review specs. It can vary by project size, number of stakeholders, etc. but this is the general flow:

1. Write a quick draft (1–2 hours)
   Close Slack and your email. Brew some tea. Sit back and think. Then jot down what you know in bullet form (see example draftfrom above).
2. Setup a couple of 30 minute 1–1 meetings (1–4 hours)
   The aim is to work through assumptions, improve your proposal, and get buy in. Keep these meetings tiny and focused with as few people in the room as possible (ideally 1–1s). For the example, I would setup 3 meetings with the support manager, a finance person, and an engineer.
3. Write and edit the spec(0.5–3 days)
   At this point you have a pretty solid idea of what can, and needs to be done, but a lot of details will be swirling in your head. Put it all together with some critical thinking and writing. And when you have a draft: do a lot of editing. You can usually make your first draft 30–50% shorter, and it’s worth it: brevity and clarity will result in it being read. Most specs can be written in 0.5–1 day, but substantial projects may take 2–3.
4. Publish and setup a 1 hour review (15 minutes)
   Send a wide email with your stakeholders on the “to” line, and other interested parties on the “cc” line (e.g. your product team, the broader support org). Follow up with a meeting invite for key people: those who will do the work, and those who have veto/approval authority.
5. Review the spec (1 hour)
   Start your spec review meeting by asking who has not read the spec in detail. There will usually be 1 or 2, in which case, say “no worries, let’s take 10 minutes to read the spec, if you have read it already, feel free to take a break”. Use this meeting to get sign off from stakeholders and get understanding and commitments from the doers (Dev, Support). You may need to revise and repeat this step based on what you learn.

After the review, send an update and file tickets (1–2 hours)
Your email should point to an updated spec, the tickets related to the project (e.g., add Javascript code, write BI reports, QA in our staging env, do a dry-run with Support team, etc.), and a rough date on when you’ll update the group next. Often, the next major step will be for an engineer to write a tech spec, but not always (my example doesn’t need it).

스펙 문서는 어떻게 쓰는가?

다음은 내가 스펙 문서를 작성하고 리뷰하는 과정이다. 프로젝트의 사이즈나 관련된 사람들의 수에 따라 달라질 수 있지만, 일반적으로 이렇게 진행된다.

1. 초안을 작성한다 (1–2시간)
   Slack과 이메일을 닫는다. 차나 커피를 가져온다. 의자에 기대앉아 생각 한다. 그리고 알고 있는 것들을 불릿 형식으로 적어나간다(예시 참고).
2. 두어 번의 30분짜리 1:1 미팅을 잡는다 (1–4시간)
   이 작업의 목표는 가정을 만들어 나가고, 제안을 개선하며, 사람들을 끌어들이는 데에 있다. 이 미팅이 거창해지지 않도록 최대한 적은 사람이 집중해 참여하게 하라(1:1 미팅이 이상적이다). 예를 들면, 이 경우에는 고객 지원 담당자, 재무 담당자, 그리고 개발자와 각각 1:1 미팅을 잡을 것이다.
3. 스펙 문서를 작성하고 수정한다 (0.5–3일)
   이 시점에서 당신은 이제 무엇을 할 수 있고, 또 해야 하는지에 대해서는 확실한 아이디어를 가지고 있을 것이나, 여러 상세한 항목들은 머릿속을 어지럽게 돌아다니고 있을 것이다. 비판적인 사고와 글쓰기로 이것들을 정리해보아라. 초안 작성을 마치고 나서는, 계속 수정해라. 보통 초안을 기준으로 30–50% 짧아지도록 할 수 있으며, 그렇게 해볼 가치가 있다. 간결성과 명확성을 높임으로써 사람들이 더 읽게 할 수 있으므로. 대부분의 스펙 문서는5–1일 안에 쓸 수 있지만, 더 규모가 있는 프로젝트의 문서 작성에는 2–3일이 걸리기도 한다.
4. 문서를 보내고 1시간짜리 리뷰 미팅을 잡아라 (15분)
   직접 관계된 사람들을 “to”에 넣고, 관련이 있을 수 있는 사람들(product team 사람들, 더 넓은 범위의 운영 조직 등)을 “cc”에 넣어서 메일을 보내라. 중요인물들을 미팅에 초대하라. 의사 결정에 거부/동의 권한이 있거나, 직접 프로젝트에 참여하는 사람들을 말한다.
5. 스펙 리뷰 미팅 (1시간)
   스펙 문서를 자세히 읽지 않은 사람이 있는지 물어보면서 시작하라. 한두 명이 이에 해당할 것이다. 그 경우“걱정하지 마세요, 다 같이 10분 동안 읽고 시작하죠. 다 읽으셨다면 잠깐 쉬고 계셔도 좋습니다.” 라고 말하고, 다 같이 읽는 시간을 가지도록 하라. 이 미팅을 통해 관계자들의 동의를 구하고, 직접 실행할 사람들(개발, 운영)에게는 책임을 확인하라. 이 과정에서 알게 된 것을 토대로 문서를 업데이트하고, 미팅을 다시 가져야 할 수도 있다.
6. 리뷰 미팅 후, 업데이트된 내용을 보내고, 티켓을 만들어라 (1–2시간)
   이 이메일에는 업데이트된 스펙 문서와 프로젝트와 관련된 티켓들의 링크(티켓들은 작업 단위로 쪼개진다 — 자바스크립트 코드 추가, BI 레포트 작성, 스테이징 서버에서 테스트, 운영팀과 함께 예행연습 등..), 그리고 언제 다음 메일을 보낼지에 대한 대략적인 언급이 있어야 한다. 종종 다음 단계는 개발자가 기술 스펙을 작성하는 것이지만, 항상 필요한 것은 아니다 (이 예시처럼 간단한 경우에는 필요하지 않다).

What are some pro-tips for writing an effective product spec?

1. Keep it short
   No spec writing advice is more important. Brevity forces clarity of thought and communication. It also means that your doc is more likely to be read and understood — because that’s all that counts.
2. Use plain English and simple formatting
   Use shorter and simpler words over fancy ones. Use bullets and bold styling to make it easy to scan your doc. Write in a casual style, and make it interesting. Use humor if you can.
3. Stay ahead of your dev team
   A completed spec is one that has been reviewed and generally agreed upon. If you’re hoping to slot in work into a future sprint, make sure you start this process 2–3 weeks before.
4. Think like an engineer
   A lot of edge cases appear when one finally sits down to write code — but that doesn’t have to be the case. If you think through what it will take to build it, you’ll address them early (e.g., does live chat work on mobile?).
5. Bring everyone on the journey
   By the time I do a spec review, most people in the room have a general idea of what’s coming — because I’ve vetted it in small focused meetings and informal chats. This means I’ve done my job in communicating the what and the why, and now we’re just focused on the details.
6. Work hard on images
   Like flow diagrams, or wireframes. They can convey huge amounts of info in an easily digestible manner, but can also take lots of time to make.
7. Spend 0.5 to 3 days thinking and writing
   Depending on how large the project is. More time than that usually results in diminishing returns, especially because nobody will read a doc that is longer than 5–6 pages.
8. Set direction and point at the vision
   You’re not just defining this one feature, but you’re also providing context on why we’re doing this and where we’re going. Point out how this project affects the grand plan, and what things may come next.
9. Make sure your Audience reads it
   If your spec is too long, confusing, or just not shared with the right people, you might as well not write it. Make sure it is read. See my tip on reading it at the start of reviews.

Get honest feedback
Are your specs specifying the obvious? Or don’t have enough detail? Are we finding too many edge cases later on? Or are we spending too much time in planning/review? Ask your team.

효과적인 스펙 문서에 관한 팁

1. 짧게 써라
   이보다 더 중요한 팁은 없다. 간결성은 사고와 커뮤니케이션에서의 명확성을 불러온다. 또한, 사람들은 짧은 문서를 더 잘 읽고 이해한다. 이게 가장 중요하다.
2. 명백한 어휘와 단순한 포맷을 사용하라
   미사여구보다는 짧고 간결한 어휘를 사용하라. 불릿과 볼드를 이용해 문서를 훑어보기 편하게 만들어라. 너무 딱딱하지 않게 쓰고, 재미있게 써라. 자신이 있다면 유머를 덧붙여도 좋다.
3. (개발팀 일정에) 앞서서 써라
   완성된 스펙 문서는 이미 검토 과정을 마치고 모두의 동의를 구한 상태여야 한다. 즉, 스프린트가 시작하기 2–3주 전에는 이 작업을 시작해야 한다.
4. 개발자처럼 생각하라
   보통은 실제 개발자가 코드를 작성할 때가 되어서야 특이 케이스들이 나타나지만, 항상 그러란 법은 없다. 어떻게 만들지를 미리 깊게 생각한다면 그런 부분을 미리 정하여 언급할 수 있다(e.g., 라이브 채팅이 모바일에서 돌아가는가?).
5. 모두를 동참시켜라
   내 프로젝트의 스펙 리뷰 미팅을 진행할 때면, 이미 대부분의 사람은 이게 어떤 것인지를 알고 있다. 내가 작은 미팅이나 비공식적인 대화/채팅을 통해서 미리 전달했기 때문이다. 이런 방법으로 ‘무엇을 왜 하는지’에 대한 커뮤니케이션을 미리 마친 상태에서 본격적으로 디테일에 집중할 수 있다.
6. 시각화에 대해 열심히 고민하라
   플로우 다이어그램이나 와이어프레임 같은 시각화는 중요하다. 많은 양의 정보를 쉽게 이해하도록 도와준다. 물론 이건 많은 시간이 필요하다.
7. 생각하고 쓰는 데에는5–3일만 써라
   이것보다 더 많은 시간을 들이는 것은 더 못한 결과를 가져오는 경우가 많다. 아무도 5–6페이지보다 긴 문서를 읽지 않을 것이기 때문에.
8. 방향과 비전을 제시하라
   단지 이 기능을 정의하는 데서 끝낼 것이 아니라, 왜 이것을 해야 하는지와, 앞으로 어떤 방향으로 갈 것인지에 대해서도 전달해야 한다. 거시적인 관점에서 이 프로젝트를 보게 하고, 다음엔 어떤 일을 진행할 것인지도 언급해주면 좋다.
9. 읽히도록 만들어라
   스펙 문서가 길거나, 정신없거나, 적절한 대상에게 공유가 되지 않았다면 당신은 문서를 쓰지 않은 것이나 다름없다. 읽히도록 만들어라. 리뷰 미팅을 시작할 때 다 같이 읽는 시간을 만드는 것도 좋다.
10. 솔직한 피드백을 받아라
    명백하게 썼는가? 아니면 정보가 불충분한가? 나중 단계에서 특이 케이스를 잔뜩 발견할 것 같은가? 기획/검토 단계에서 너무 많은 시간을 들이고 있는가? 팀에게 물어봐라.

But what about Agile and Scrum?

I know I will raise eyebrows, but specs are fully compatible with the principles of the blog, and are essentially represented in methodologies like Scrum — after all, don’t stories need more meat put on them at some point? Why have verbal and whiteboard sessions, only to then lose the clarity and communication value that comes from writing it down?

The view that specs result in slower releases, over-planning, and generally wasted time is unfounded. Multiple world-class teams I have worked on followed several agile principles (like 2-week sprints), shipped code daily (or more), and measured their success on product shipped (not documentation or meetings) — yet still prized specs as a key part of their process.

And what about tech specs?

I’m a huge fan. While product specs focus on the what, tech specs focus on the how. They bring the same clarity to a different part of the building process, and ultimately make engineers (and their customers) happier. I may write about tech specs in a future post if there is interest.

In Conclusion

Thanks for reading this far. If you’ve found this post useful, please do share with your product and engineering teams. Happy day!

Question :

It seems that in order to write an effective spec, a product manager would need a decent understanding of how businesses work (to frame goals and requirements in a way that can get high-level sign-off); and also the ability to grok how-engineers-think; and experience to know the specific “gotchas” around BI metrics and operations.

That’s a lot. I realize it’s a somewhat leading question, but how should companies hire and train product managers? If an organization doesn’t have a senior product manager with experience in all these areas, any advice for how they can still write specs with the right level of thought around what’s out of scope, setting measurable goals, etc?

광고