진행 중인 개인 프로젝트의 초안입니다. 팀에서 실제로 사용한 뒤 읽는 과정에서 막힌 부분과 활용 결과를 보완할 예정입니다.
팀 온보딩과 인수인계를 준비하면서 프로젝트 통합 설명 문서를 만들기 시작했다. 자료를 정리하다 보니 한 가지 질문이 남았다. 내가 알고 있는 내용을 설명할 수는 있지만, 그 설명을 듣지 않은 동료도 같은 근거를 가지고 판단할 수 있을까.
나는 이제 3년차 개발자다. 구현을 이해하는 범위와 함께, 그 이해가 다른 사람의 작업에 어떻게 도움이 되는지도 생각하려고 한다. 내가 일을 처리하는 속도뿐 아니라 동료가 필요한 맥락을 얻고 다음 행동을 결정하는 데 드는 시간에도 관심을 갖게 됐다.
통합 문서는 그 관심을 구체적인 작업으로 옮기는 방법이다. 프로젝트를 처음 보는 사람에게 읽는 순서를 제공하고, 익숙한 사람에게는 설명의 근거를 확인할 수 있는 경로를 남기려 한다.
지금 이 작업에서 중요하게 보는 기준은 세 가지다.
- 읽는 사람이 자신의 질문에 맞는 출발점을 찾을 수 있어야 한다.
- 설명을 읽고 관련 원문과 코드까지 확인할 수 있어야 한다.
- 변경이 생겼을 때 다시 검증하고 고칠 수 있는 구조여야 한다.
프로젝트를 이해하는 데도 진입점이 필요하다
문서가 흩어져 있으면 독자는 내용을 이해하면서 읽는 순서까지 설계해야 한다. 어떤 설명이 현재 프로젝트의 범위에 해당하는지, 무엇을 먼저 알아야 하는지, 지금도 유효한 내용인지 판단하는 부담이 함께 생긴다.
프로젝트에 익숙한 사람이 이 비용을 놓치기 쉽다는 점을 의식하고 있다. 익숙한 사람은 문서에 생략된 연결을 기억으로 메울 수 있다. 처음 보는 사람에게는 그 연결도 설명이 필요하다. 내가 빠르게 찾을 수 있다는 이유만으로 다른 사람에게도 찾기 쉬운 구조라고 판단하기 어렵다.
그래서 통합 문서를 하나의 사용 경험으로 보고 있다. 처음 방문한 사람이 전체 맥락을 잡고, 맡은 영역으로 이동하고, 자세한 근거를 확인하는 과정이 이어져야 한다. 목차와 검색은 그 과정을 돕는 장치다. 페이지를 찾은 뒤에도 현재 위치와 다음으로 읽을 곳을 알 수 있어야 한다.
전체 구조와 역할별 읽는 순서를 앞에 두고, 상세 설명에서 원문으로 이어지는 연결을 만드는 이유다. 처음부터 모든 자료를 읽게 하기보다, 지금 필요한 판단에 충분한 맥락을 제공하고 더 깊이 들어갈 길을 남기고 싶다.
설명을 공유하면 판단의 출발점도 공유할 수 있다
온보딩에서 기대하는 변화는 기본적인 맥락을 얻는 과정이 더 명확해지는 것이다. 새로 온 사람이 문서를 먼저 읽고 자신의 이해를 정리하면, 대화에서는 빠진 연결이나 실제로 판단이 필요한 부분을 다룰 수 있다.
질문의 질도 확인하고 싶다. "이 프로젝트는 어떻게 되어 있나요?"라는 질문에서 "이 책임은 여기까지라고 이해했는데, 변경할 때 어떤 제약을 고려해야 하나요?"라는 질문으로 이어지면 설명하는 사람과 듣는 사람이 함께 생각할 수 있는 범위가 넓어진다.
이때 문서에 남겨야 할 맥락은 현재의 동작뿐 아니라 그 선택이 성립하는 조건이다. 당시의 제약, 고려했던 대안, 우선한 기준을 확인할 수 있으면 나중에 조건이 바뀌었을 때도 판단을 이어갈 수 있다. 이유를 확인할 수 없는 규칙은 그대로 따르기만 하거나, 필요성을 이해하지 못한 채 바꾸기 쉽다.
통합 문서가 이런 맥락을 모두 담고 있는 것은 아니다. 지금은 설명이 비어 있는 곳을 찾고 근거를 연결하는 과정이다. 확인할 수 없는 이유까지 그럴듯하게 채워 넣기보다, 추가로 확인해야 할 질문으로 남기려 한다.
이 작업에는 개인에게 집중된 지식의 전달 비용을 줄이고 싶은 생각도 있다. 담당자의 설명은 여전히 필요하다. 다만 기본적인 사실과 범위를 함께 참고할 수 있으면, 설명을 요청하는 사람도 자신의 질문을 준비할 수 있고 담당자도 같은 출발점부터 반복하는 부담을 덜 수 있다.
AI의 조사 결과에는 사람을 위한 편집이 필요하다
AI는 흩어진 자료를 찾고, 코드와 문서를 대조하고, 빠진 설명 후보를 모으는 데 활용한다. 그 결과를 읽는 사람의 질문과 이해 순서에 맞춰 편집하는 일은 별도로 진행하고 있다.
읽는 사람은 조사 과정을 함께 겪지 않았다. 어떤 용어를 먼저 알아야 하는지, 왜 이 설명이 필요한지, 다음에 무엇을 확인해야 하는지가 문서 안에 드러나야 한다. 처음 등장하는 용어를 설명하고, 큰 구조에서 세부 내용으로 내려가고, 설명에 사용한 근거를 연결하는 데 시간을 쓰고 있다.
AI를 활용할수록 설명의 확신 정도도 확인하려 한다. 코드에서 직접 확인한 동작, 과거 문서에 적힌 의도, 아직 검증하지 못한 추정은 신뢰할 수 있는 범위가 다르다. 문장이 매끄럽다는 이유로 모두 같은 확신으로 전달되면 읽는 사람이 판단할 단서가 사라진다.
현재 포털의 검색 기능을 공개용 예시 내용으로 캡처했다. 실제 사내 문서의 제목과 본문은 포함하지 않았다.
설명과 근거를 함께 두는 방식은 내 이해를 점검하는 데도 도움이 된다. 문장을 쓰다가 근거를 연결하지 못하면 내가 알고 있다고 생각했던 내용의 범위부터 다시 확인하게 된다. 문서를 작성하는 과정 자체가 이해의 빈틈을 찾는 작업이 된다.
좋은 문서는 변경된 뒤에도 관리할 수 있어야 한다
통합 문서에는 유지 비용이 따른다. 내용을 자세히 복제할수록 원문이 바뀌었을 때 함께 수정해야 할 곳이 늘어난다. 반대로 링크만 나열하면 처음 읽는 사람이 맥락을 직접 조합해야 한다. 지금은 전체 맥락은 설명으로 남기고, 세부 사항은 원문과 구현 위치로 연결하는 방식으로 균형을 잡으려 한다.
최신성도 독자가 확인할 수 있어야 한다. 설명을 언제 어떤 근거로 확인했는지, 검증하지 못한 항목이 무엇인지 드러나면 그 문서를 사용할 수 있는 범위를 판단할 수 있다. 잘못된 내용이 발견됐을 때 수정할 위치가 분명한 것도 중요하다.
완성도와 유지 가능성을 함께 보려는 이유다. 한 번 정리해 둔 자료가 시간이 흐른 뒤에는 신뢰하기 어려운 참고 자료가 될 수 있다. 문서가 늘어난 만큼 관리할 수 있는지, 변경이 생겼을 때 어떤 설명을 다시 확인해야 하는지도 계속 살펴봐야 한다.
효과를 확인할 때도 문서의 개수만 세고 싶지는 않다. 새로 온 사람이 필요한 설명을 어디에서 찾는지, 어떤 질문이 계속 반복되는지, 원문으로 이동해 스스로 확인할 수 있는지 보고 싶다. 읽는 사람이 막힌 지점을 받아 문서 구조를 고치는 과정까지 문서화 작업에 포함하려 한다.
내가 없는 순간에도 설명이 이어지도록
나는 내가 이해한 내용을 다른 사람이 활용할 수 있게 만드는 일도 개발자의 책임에 포함된다고 생각한다. 함께 일하는 사람이 맥락을 얻고 판단할 수 있으면, 내가 직접 설명하지 않는 순간에도 작업이 이어질 수 있다.
연차가 쌓일수록 내가 맡은 작업이 끝나는 지점과 다음 사람이 이어받는 지점을 함께 보려 한다. 코드를 작성하고 설명을 남기는 과정에서, 상대가 무엇을 알고 있어야 하는지와 어디까지 스스로 확인할 수 있는지를 생각하는 습관을 만들고 싶다.
현재는 개인적으로 추진하고 있는 프로젝트다. 실제 온보딩 시간이 줄었는지, 팀의 활용도가 높은지 측정한 결과는 아직 없다. 팀원이 읽고 질문을 남기는 과정에서 기대와 다른 부분도 확인할 수 있을 것이다.
내가 만들고 싶은 문서는 처음 보는 사람에게 다음으로 읽을 곳을 알려주고, 대화할 때 함께 참고할 수 있고, 시간이 지난 뒤에도 판단의 근거를 되짚을 수 있는 문서다. 이런 기반을 정리하는 일을 팀에 기여하는 방법으로 계속 가져가고 싶다.