결제 플랫폼 README 반년치 부패 한 번에 정리

README 업데이트, 한 시간이면 끝날 줄 알았음

결제 플랫폼 사이드 레포 README가 반년째 방치돼 있길래 가볍게 손보려고 함. 결과적으로 두 시간 넘게 붙잡고 있었음. 문서가 코드보다 빨리 썩는다는 말이 진짜라는 걸 또 체감.

뭐가 문제였나

기존 README 훑어보니 다음 같은 이슈들이 보였음.

• 설치 가이드의 의존성 버전이 두 단계 뒤처져 있음
• "TODO" 섹션이 작년 분기 로드맵 그대로 남아있음
• 환경변수 목록 절반이 사라진 변수, 새 변수는 누락
• 아키텍처 다이어그램이 파트너 연동 추가 전 버전

코드는 누가 안 고치면 바로 빌드가 깨지는데, 문서는 틀려도 아무도 모름. 그래서 점점 거짓말이 쌓임.

정리한 원칙

이번에 손보면서 스스로 룰을 몇 개 정함.

특히 트러블슈팅은 욕심내면 끝이 없어서 "최근 6개월" 컷오프를 둠. 오래된 케이스는 사내 위키로 빼버림.

빠른 시작 다듬기

기존 빠른 시작이 지나치게 친절했음. 한 줄이면 될 걸 다섯 줄로 풀어 적어놓음. 결국 이 정도로 압축.

cp .env.example .env
make bootstrap
make run

이게 안 되면 README가 아니라 make 타겟을 고쳐야 한다는 결론. 문서로 우회하지 말고 도구가 친절하게 되도록 만드는 게 맞음.

배운 것

• README는 현재 시제로만 적기. "예정"/"준비중" 들어가면 무조건 거짓말 됨
• 변경 PR 템플릿에 "README 영향 있음/없음" 체크박스 넣어두니 다음부터 덜 썩을 듯
• 다이어그램은 텍스트로 옮길 수 있으면 옮기는 게 유지보수 쉬움. mermaid 정도면 충분함
• "예시 응답"에 실제 파트너 식별자 박혀있는 거 발견. 더미값으로 교체. 문서가 보안 구멍 될 수 있다는 걸 늦게 깨달음

회고

문서 작업은 항상 견적이 두 배로 나옴. 그래도 README 한 번 빡세게 정리하고 나면, 새 멤버 온보딩 질문이 눈에 띄게 줄어드는 게 보임. ROI는 분명히 있음.

다음 PR부터는 코드와 문서를 같은 단위로 묶어서 올리는 습관을 들이는 게 목표. 다음.