장애 보고서에 "it stopped working"만 쓰면, 원인 분석이 사라집니다
스탠드업에서 "I'm working on the payment bug, almost done" 정도는 입에서 잘 나옵니다. 짧고, 상대도 맥락을 아니까요. 그런데 같은 사람이 ADR(설계 결정 기록)이나 포스트모템을 영어로 쓰기 시작하면 갑자기 문장이 막힙니다.
이유는 간단합니다. 스탠드업 영어는 '지금 뭐 하는지'를 말하면 되지만, 설계 문서와 장애 보고서는 '왜 그렇게 판단했는지'를 남겨야 하거든요. 근거, 대안, 트레이드오프, 당시엔 몰랐던 것. 이걸 영어로 옮기려다 보면 문장이 뭉개지고, 결국 "it just works better"나 "it stopped working" 같은 말로 도망가게 됩니다.
문제는 이 문서들이 나중에 다시 읽힌다는 점이에요. 6개월 뒤 다른 팀이 "왜 이렇게 설계했지?" 하고 찾아올 때, 내가 쓴 흐린 문장이 그대로 남습니다. 오늘은 ADR과 장애 보고서에서 자주 흐려지는 다섯 자리를, 예문으로 하나씩 고쳐볼게요.
"그게 더 낫다"를 쓸 때, 비교 대상이 사라집니다
설계 결정에서 제일 흔한 실수는 "A가 더 낫다"고만 쓰고 끝내는 거예요. 무엇보다 나은지, 어떤 기준에서 나은지가 빠지면 독자는 판단을 재현할 수 없습니다.
before 문장의 문제는 "better"가 혼자 서 있다는 점입니다. 영어에서 비교급은 "A보다"(than B)와 "어떤 점에서"(in what way)를 끌고 다녀야 정보가 됩니다. after에서는 over MongoDB로 대상을 명시하고, valued X more than Y 구문으로 트레이드오프를 그대로 드러냈어요. 설계 결정은 '무엇을 포기했는지'가 '무엇을 골랐는지'만큼 중요하거든요. consistency를 위해 flexibility를 내줬다, 이 교환이 보여야 문서가 됩니다.
장애 원인을 쓸 때, "it stopped"는 주어를 숨깁니다
포스트모템에서 "서비스가 멈췄다"를 "it stopped working"으로 쓰면, 무엇이 무엇을 멈추게 했는지가 안개 속으로 들어갑니다. 원인 분석의 핵심은 주어와 동사를 정확히 짚는 거예요.
"stop working"은 결과만 말합니다. 반면 ran out of connections는 원인 메커니즘을 주어로 끌어올렸어요. 영어에서 장애 원인을 쓸 때는 타동사를 적극적으로 쓰는 게 좋습니다. blocked, triggered, exhausted, overwhelmed처럼 '무엇이 무엇에 작용했는가'를 드러내는 동사요. which blocked all login requests는 관계대명사로 원인과 결과를 한 문장에 묶었습니다. "그리고 유저가 로그인 못 했다"가 아니라 "그래서 막혔다"로 인과가 서는 거죠.
시점이 섞이면, "그때 몰랐던 것"이 "지금도 모르는 것"처럼 읽힙니다
장애 보고서에서 시제는 생각보다 민감합니다. 장애 당시의 판단과 지금 알게 된 사실을 같은 시제로 쓰면, 읽는 사람은 "아직도 원인을 모르나?" 하고 오해해요.
before는 모든 동사가 현재형이라, 장애가 아직 진행 중이고 원인도 미궁인 것처럼 들립니다. after는 시점을 둘로 나눴어요. At the time ... didn't know로 당시의 제한된 정보를 과거에 묶고, We now understand로 현재의 결론을 분리했습니다. 이게 포스트모템의 기본 뼈대예요. 과거의 대응을 비난하지 않으면서도, 지금은 더 안다는 걸 시제만으로 보여줄 수 있습니다. as a temporary fix 한 마디로 "임시방편이었음을 알고 있었다"까지 깔끔하게 전달돼요.
트레이드오프를 쓸 때, "하지만"만으로는 저울이 안 보입니다
좋은 설계 결정 기록은 장단점을 저울에 올립니다. 그런데 but 하나로 이으면, 두 항목이 대등하게 비교되는지 그냥 변명을 덧붙인 건지 구분이 안 돼요.
before의 but은 두 사실을 나열할 뿐, 둘 사이의 교환 관계나 내가 내린 선택이 안 보입니다. after는 at the cost of로 "이걸 얻는 대신 저걸 내줬다"는 저울을 명시했어요. 그리고 We accepted this trade-off because로 왜 그 저울에서 이쪽을 골랐는지까지 썼습니다. ADR의 핵심이 바로 이 마지막 문장이에요. 트레이드오프를 '인지했다'와 '받아들였다'는 다릅니다. accepted라는 동사 하나가 "우리는 이 비용을 알고도 선택했다"는 판단의 주체성을 세워줍니다.
재발 방지책을 쓸 때, "should"는 계획이 아니라 소망입니다
포스트모템 마지막의 액션 아이템. 여기서 "우리는 모니터링을 추가해야 한다"를 should로 쓰면, 책임자도 기한도 없는 소망처럼 떠버립니다.
should는 "그러면 좋겠다"는 당위를 표현합니다. 방향은 맞지만 아무도 묶이지 않아요. after는 will로 바꿔 약속으로 만들고, 무엇을(connection-pool alerts), 언제까지(by next sprint), 누가(owned by the platform team)를 붙였습니다. 액션 아이템이 실제로 굴러가려면 이 세 가지가 문장 안에 있어야 해요. "more monitoring"처럼 뭉뚱그린 명사도 피하세요. 무엇을 모니터링할지 구체적으로 써야 다음 사람이 그걸 확인할 수 있습니다.
정리하면, 설계 결정과 장애 보고서의 영어는 '상태'가 아니라 '판단'을 쓰는 글입니다. 비교엔 대상을, 원인엔 주어를, 당시와 지금엔 다른 시제를, 트레이드오프엔 저울을, 재발 방지엔 담당과 기한을 붙이세요. 다섯 자리만 챙겨도 문서가 훨씬 또렷해집니다.
그리고 이렇게 고쳐 쓴 문장들은 한 번 쓰고 흘려보내기엔 아깝습니다. 내가 어떤 자리에서 흐려졌고 어떻게 고쳤는지가 쌓이면, 다음 포스트모템은 조금 덜 막혀요. 오늘 장애 하나를 복기한 김에, 그 보고서 문장 하나를 직접 영작해 두는 것부터 해보세요.