코드로 알 수 없는 것
무엇을 하는지는 코드가 말합니다. 문서가 담을 것은 왜 이렇게 했는지, 어떤 대안을 왜 버렸는지, 무엇을 조심해야 하는지입니다.
이 파트에서 다루는 내용
왜 문서를 쓰나무엇을 쓰나결정을 기록하기문서를 유지하기
01
문서의 목적은 미래의 누군가에게 시간을 벌어 주는 것입니다
문서를 쓰라고 하면 형식과 분량에 눌려 시작을 못 합니다. 그러나 좋은 문서의 기준은 분량이 아니라, 나중에 이걸 읽을 사람의 시간을 얼마나 아껴 주느냐입니다.
그 사람은 대개 몇 달 뒤의 나 자신이거나 새로 합류한 동료입니다. 지금 내 머릿속에 있는 맥락은 반드시 사라집니다. 사라지기 전에 붙잡아 두는 것이 문서입니다.
읽는 사람 기준
쓰는 내가 아니라 읽는 사람이 기준입니다. 처음 보는 사람이 이것만 읽고 시작할 수 있는가를 물으며 씁니다.
완벽보다 존재
없는 완벽한 문서보다 있는 거친 문서가 낫습니다. 짧아도 지금 남기는 것이, 나중에 제대로 쓰겠다며 안 남기는 것보다 낫습니다.
02
실무에서 실제로 읽히는 문서는 정해져 있습니다
모든 것을 문서화하려 하면 아무것도 유지되지 않습니다. 실제로 반복해서 읽히는 몇 가지에 집중합니다.
README
이 프로젝트가 무엇이고 어떻게 실행하는지. 새 팀원이 가장 먼저 봅니다. 트랙 A의 온보딩이 여기서 시작됩니다. 실행 절차가 최신인지가 가장 중요합니다.
설계 메모
복잡한 기능을 만들기 전에 접근 방식을 짧게 적습니다. 코드를 짜기 전에 방향을 리뷰받을 수 있고, 나중에 왜 이렇게 했는지 근거가 됩니다.
트러블슈팅 기록
어렵게 해결한 문제는 증상·원인·해결을 남깁니다. 터미널 코스에서 강조한 기록과 같습니다. 같은 문제로 다음 사람이 헤매지 않습니다.
운영 문서
배포 절차, 롤백 방법, 자주 나는 장애 대응. 급한 순간에 찾는 문서라 위치와 최신성이 특히 중요합니다.
03
결정은 이유와 함께 기록합니다
가장 자주 사라지고 가장 아쉬운 것이 왜 그렇게 결정했는가입니다. 몇 달 뒤 왜 이 라이브러리를 썼지, 왜 이 구조로 했지를 아무도 기억하지 못합니다.
결정 기록은 길 필요가 없습니다. 무엇을 정했고, 왜 정했고, 어떤 대안을 왜 버렸는지 몇 줄이면 됩니다. 이것이 나중에 재검토할 때 출발점이 됩니다.
되돌릴 수 없는 결정일수록
바꾸기 어려운 결정일수록 기록의 가치가 큽니다. 데이터 구조, 외부 연동, 아키텍처 선택이 그렇습니다. 트랙 C의 의사결정과 이어집니다.
코드 가까이 둔다
결정 기록을 저장소 안에 두면 코드와 함께 버전 관리되고 찾기 쉽습니다. 별도 시스템에 흩어지면 아무도 안 봅니다.
결정 기록 형식text
## 결정: 서버 상태 관리에 전용 라이브러리 도입
### 배경
조회 화면이 늘면서 로딩·오류·캐시 코드가 화면마다
복사되고 있었다. (React 코스 Part 9 상황)
### 결정
서버 상태 전용 라이브러리를 도입한다.
### 이유
- 캐시와 갱신을 직접 구현하던 코드가 반복됨
- 경쟁 상태 처리를 매번 놓침
### 검토했으나 버린 대안
- 전역 상태에 직접 저장: 갱신 로직을 계속 만들어야 함
- 현행 유지: 화면이 늘수록 중복이 커짐
### 남는 리스크
- 러닝 커브. 팀 공유 세션으로 완화.이런 기록 하나가, 반년 뒤 왜 이걸 썼냐는 질문과 되돌리자는 논의를 몇 시간 아껴 줍니다. 형식은 팀에 맞게 줄여도 됩니다.
04
틀린 문서는 없는 문서보다 나쁩니다
문서의 가장 큰 적은 낡음입니다. 실제와 다른 문서는 읽는 사람을 잘못된 길로 이끌어, 없느니만 못한 상태가 됩니다.
그래서 유지할 수 없는 문서는 처음부터 만들지 않는 편이 낫습니다. 무엇을 문서로 남기고 무엇을 코드와 테스트에 맡길지 판단합니다.
자주 바뀌는 것은 코드에
세부 구현처럼 자주 바뀌는 것은 문서로 두면 금방 낡습니다. 코드와 테스트가 스스로 말하게 하고, 문서는 잘 안 바뀌는 맥락과 이유를 담습니다.
바꿀 때 함께 갱신
코드를 바꾸면 관련 문서도 같은 PR에서 갱신합니다. 나중에 하겠다는 것은 안 하겠다는 뜻입니다. README의 실행 절차가 대표적입니다.
낡은 문서는 지운다
더 이상 맞지 않는 문서는 붙잡지 말고 지우거나 낡음을 표시합니다. 틀린 정보를 남겨 두는 것이 가장 위험합니다.
작성 시점 표시
버전과 시점에 따라 달라지는 내용은 언제 쓴 것인지 밝힙니다. 이 학습 사이트가 각 자료에 작성 기준을 표시하는 것과 같은 이유입니다.
정리
문서는 미래의 누군가에게 시간을 벌어 주는 일입니다. 실제로 읽히는 것에 집중하고, 왜 그렇게 했는지를 남기고, 낡지 않게 유지합니다. 완벽한 문서를 목표로 미루기보다, 짧아도 지금 남기고 바뀔 때 함께 고치는 편이 낫습니다.
체크