테크스펙 작성을 위한 효과적인 가이드라인 (A practical guide to writing technical specs)
스택오버플로우 블로그 글에 올라온 https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/ 를 번역한 글입니다. 오역, 의역이 많을 수 있으니 참고 부탁드립니다.
소프트웨어 엔지니어인 당신의 해야할 일은 기술적 문제들을 해결하는 것이다. 이를 위해 바로 코드 작성을 하고 싶겠지만, 해결책에 대한 일말의 생각 없이 코드 작성을 시작하는 것은 아주 끔찍한 생각이다.
당신이 테크스펙을 작성하는 것으로 어려운 기술적 문제들을 생각할 수 있고, 글솜씨가 영 별로라면 하나를 쓰는 것에 있어 답답하다고 생각할 수 있습니다. 아마 불필요한 잡일 정도로 생각할 수도 있겠다. 하지만 테크스펙을 작성한다면 프로젝트의 이해관계자들이 만족하는 성공적인 프로젝트, 서비스 또는 기능을 산출물로서 가질 확률이 증가한다. 그리고 구현하는 동안, 여러 지뢰밭을 밟을 일도 줄어들고 배포 후에 골머리를 썩게 만드는 버그의 출현을 줄일 수 있다.
이 글에서는, 훌륭한 제품(strong product)을 위한 테크스펙 작성법에 대해 이야기 하도록 하겠다.
테크스펙이란 무엇인가?
테크스펙은 해결책을 설계하고 구축하여 기술적 문제를 해결하는 방법을 설명하는 문서이다. 이 문서는 기술 설계 문서, 소프트웨어 설계 문서 등의 이름으로 불리기도 한다. 개발을 진행할 실무진이 주로 작성하지만, 대규모 프로젝트의 경우 프로젝트책임자, 테크리드, 기술 책임자가 작성하기도 한다. 이 문서는 기능, 프로젝트, 프로그램 또는 서비스의 디자인, 관련 작업, 영향 및 타임라인을 엔지니어 팀 및 기타 이해관계자에게 보여주는 역할을 한다.
테크스펙을 쓰는 것은 왜 중요한가?
테크스펙은 프로젝트와 관련된 사람들(문서를 쓴 엔지니어, 문서를 보는 팀들, 그 문서로 설계된 프로젝트에 대한 모든 것)에게 큰 이점을 가져다 준다. 몇몇 이유를 아래에 정리해 보았다.
엔지니어에게 주는 이득
테크스펙을 쓰면서 엔지니어들은 코드작성을 하기 전에 해결책을 생각하면서 간과한 부분에 대한 문제를 조사할 수 있습니다. 구현을 위해 필요한 작업들을 세분화하고 구성하며 시간 제한을 설정하면, 해결책의 범위를 더 잘 파악할 수 있다. 테크스펙은 제안된 해결책에 대한 철저한 하나의 뷰이기 때문에 구현 단계, 그리고 그 이후까지도 프로젝트에 대한 문서로 사용되어 프로젝트에 대한 성과를 전달하는 역할도 수행한다.
잘 생각한 해결책을 테크스펙으로 작성한 것으로 여러 팀원 및 이해관계자에게 해결책을 위한 설계와 진행 계획을 반복적으로 설명하지 않아도 된다. 그렇지만 모두가 완벽할 수는 없다. 당신의 동료나 더 경험많은 선배 엔지니어는 설계에 대해 당신이 생각하지 못했던 신기술이나 기술 사례, 대안 등등을 보여줄 수 있다. 그들이 당신이 놓쳤을 예외 케이스를 포착하여 당신의 책임을 줄여줄 수 있다. 그러므로 테크스펙은 리뷰어가 많을 수록 좋다.
팀에게 주는 이득
테크스펙은 팀과 다른 이해관계자들이 프로젝트 디자인 아이디어를 소통할 수 있는 직설적이고 효율적인 방법 중 하나이다. 전체 팀은 협력적으로 문제를 해결하고 해결책을 제시할 수 있다. 이해관계자와 동료들이 스펙에 기여할 수록, 그들은 프로젝트에 더 많은 시간을 투자하고 소유권과 책임을 함께 가질 수 있다. 모두가 한 맥락에 있기 때문에 겹치는 작업으로 발생하는 복잡함을 줄여 준다. 그리고 프로젝트에 익숙하지 않은 새 팀원은 스스로 온보딩을 진행하고 더 일찍 구현에 기여할 수 있다.
프로젝트에게 주는 이득
테크스펙에 투자하면 궁극적으로 우수한 제품이 탄생한다. 팀은 스펙을 통해 완료되어야 하는 과업들이 무엇인지에 대해 동의하고 정렬되어 있기 때문에, 큰 프로젝트를 빠르게 수행할 수 있다. 테크스펙은 복잡성을 관리하고 프로젝트에 제한을 설정하므로 범위 및 기능의 과도한 확장을 방지하기 위해선 필수적이다. 우선 순위를 설정하여 프로젝트에서 가장 영향력 있고 긴급한 부분이 먼저 진행될 수 있도록 한다.
구현 후에는 테크스펙은 포스트모템과 회고에서 인사이트를 제공하여 프로젝트 내부에서 발생한 문제를 해결하는 데 도움을 준다. 가장 잘 계획된 사양은 개발 기간에 대비한 성공과 수익을 측정하기 위한 가이드 역할도 수행할 수 있다.
테크스펙을 쓰기 전에 해야할 것
테크스펙을 쓰기 전, 도메인의 문제점에 대한 정보를 수집해야 한다. 제품 팀이 생성한 모든 제품/기능 요구사항을 검토하고, 프로젝트와 관련된 기술 요구사항과 표준도 함께 검토한다. 문제의 히스토리에 대한 지식과 함께, 문제를 자세히 설명하고 그것을 해결 하기 위한 모든 종류의 해결책을 브레인 스토밍 하려고 노력해야 한다. 그 곳에서 끄집어 낼 수 있는 옵션들 중에서 가장 합리적은 해결책을 고르자.
한 가지 기억해야 할 것은 이 과정에서 당신은 혼자가 아니다. 당신이 공명판이 될 문제에 대해 잘 아는 경험 많은 엔지니어에게 질문을 해보자. 그들을 팀 회의에 초대하고 문제와 당신이 선택한 해답에 대해 설명해 보라. 당신의 아이디어와 생각했던 절차들을 늘어 놓고 당신의 솔루션이 가장 적절하다고 설득해 보자. 그들의 피드백을 수용하고 당신의 테크스펙 리뷰어로 설정하여 많은 것들을 물어 보라.
마지막으로, 이제 테크스펙을 작성할 시간이다. 캘린더에서 테크스펙에 집중할 수 있는 시간을 마련해라. 여러 명이 작성하는 경우 문서 작성을 위한 협업툴을 사용해 보자. 아래에 있는 테크스펙 템플릿을 가지고 초안을 작성해 보자.
테크스펙 내용
오늘날에도 수많은 회사들이 풀어야 할 광범위한 문제들이 있다. 각각의 조직은 고유한 엔지니어링 문화를 만든다. 결과적으로, 테크스펙은 같은 회사, 조직, 팀 그리고 심지어는 같은 팀의 엔지니어들 사이에서도 표준이 될 수 없다. 모든 솔루션은 서로 다른 요구사항을 지니며 프로젝트에 따라 테크스펙을 조정해야 한다. 아래 언급한 모든 영역들이 필요하지 않을 수 있다. 경우에 따라 아래 섹션을 조합하고 제거하며 선택하여 사용하도록 하자.
필자의 경험상, 테크스펙에는 7가지의 중요한 파트가 있다. (당면한 문제, 개요, 해결책, 추가 고려 사항, 성공 평가, 작업, 중요 고려사항, 완료정의)
(양식은 원문 참고)
테크스펙을 작성하고 나서
테크스펙을 작성하고 나서는 다듬을 시간이다. 마치 리뷰어가 된 것 처럼 초안을 다시 살펴보자. 스스로에게 불명확하고 불확실한 계획에 대해 질문해 보자. 이러한 것들을 초안에서 다듬어 보자. 테크스펙 만으로 설계를 구현하는 것 처럼 초안을 두번정도 검토하자. 당신이 없어도 팀이 작업할 수 있는지 테크스펙이 명확하게 작성되어 있는지 확인해라. 해결책에 대한 의문이 있고 제대로 작동하는지에 대한 테스트를 하고 싶다면 PoC(개념증명) 프로토타입을 만들어 보자.
철저히 검토한 후 초안을 팀과 이해 관계자에게 보내라. 가능한 빨리 모든 의견, 질문 제안들을 처리하자. 모든 이슈에 대한 실행 데드라인을 설정하자. 팀이 나누어져서 작업을 수행하거나 테크스펙에 대해 비정상적으로 긴 토론을 하고 있다면 회의를 통해 빠르게 해결해 보도록 하자. 그것들을 해치우기 위한 대면 미팅 이후에도 합의안을 이끌어 내는데 실패한다면, 당신의 책임 하에 최후 통첩을 진행해야 한다. 다른 팀의 엔지니어들에게 리뷰를 요청하여 외부인의 관점도 수용해야 한다. 이는 팀의 일부가 아닌 다른 이해 관계자에게 전달하는 방식을 향상시킬 것이다. 구현 중에도 설계, 일정, 작업에 대한 각, 범위 등의 변경사항은 문서에 즉각적으로 반영하여 최신 상태를 유지해야 한다.
결론
테스트 스펙을 작성하는 것은 프로젝트의 성공을 보장하는 영향력 있는 방법이 될 수 있다. 작업을 작게 쪼개고 계획할 수록 전체 프로젝트에 대한 구현을 확실히 더 쉽게 만들 수 있다.