영문 README 정비로 프로젝트 문서 품질 높이기

문서 작업은 다들 대충 하고 넘어간다. 그리고 나중에 반드시 후회한다. 이번에 오래된 사이드프로젝트 README를 영어로 다시 쓰면서, 그 작업이 단순히 글 고치는 게 아니라 프로젝트 구조 자체를 다시 들여다보는 계기가 됐음.

README를 손보다 보면 자연스럽게 "이 기능은 왜 있는 거지?", "이 디렉토리는 뭘 하는 곳이지?"를 스스로 묻게 된다. 코드는 계속 달라지는데 문서는 처음 만든 시점에서 멈춰있는 경우가 대부분이라, 결국 README가 죽어있는 repo는 6개월 뒤 내가 봐도 낯설다. 그게 가장 현실적인 이유.

README에 반드시 들어가야 할 것들

어떤 형태든 README에 빠지면 안 되는 항목이 있다. 직접 여러 repo를 오가면서 정리한 기준이라 일반론이지만, 실제로 많이 빠져 있는 것들이기도 함.

## 프로젝트 개요
어떤 문제를 해결하는지 1-2줄로. 기술 스택 나열보다 "무엇을 위한 것인지"가 먼저.

## 설치 방법
복붙 가능한 명령어 위주로. 버전 명시 필수.

## 환경 변수
| 키 | 설명 | 필수 여부 | 예시값 |

## 로컬 실행
최소한 "이 명령어 하나면 돌아간다"는 게 있어야 함.

## 아키텍처 다이어그램
있으면 이해 속도가 완전히 달라짐. 없으면 텍스트로라도 구조 설명.

프로젝트 개요에서 기술 스택부터 나열하는 경우를 많이 봤는데, 읽는 사람 입장에서는 "그래서 뭐 하는 건데?"가 먼저다. Next.js, TypeScript, PostgreSQL이라고 써놓는 건 그다음 얘기. 아키텍처 다이어그램은 간단한 ASCII로도 충분하다. Mermaid 지원이 되는 환경이면 더 좋고.

환경 변수 섹션이 빠져있는 repo가 생각보다 많다. 초기 세팅할 때 .env.example이 없으면 어디서부터 시작해야 할지 막막함. 예시값까지 같이 적어두는 게 진짜 친절한 문서다.

한국어 vs 영어, 뭘로 쓸 건지

오픈소스나 외부 공개 목적이면 영어로 쓰는 게 맞다는 건 당연한 얘기고, 기준이 애매한 게 내부 프로젝트일 때다.

상황	선택	이유
내부 팀 전용	한국어 OK	속도 우선, 독자 고정
오픈소스	영어 필수	접근성, 기여자 범위
포트폴리오	영어 권장	검색 노출, 외부 열람
내부+잠재 오픈소스화	처음부터 영어	나중에 바꾸는 게 더 힘듦

내부 프로젝트도 팀원이 여럿이면 영어 쪽이 검색 효율이 좋다. 한국어 주석이나 문서는 IDE 내 코드 검색, 이슈 트래커 검색할 때 노이즈가 생기는 경우가 있음. 특히 기술 용어는 영어인데 설명만 한국어로 혼재된 상태가 제일 피해야 할 케이스다.

이번 작업처럼 기존 한국어 README를 영어로 옮길 때는 단순 번역보다 재작성 관점으로 접근하는 게 낫다. 번역체 영어가 그냥 뭉개진 한국어보다 못한 경우가 있어서, 쓰면서 문장 자체를 다시 구성했음.

코드를 쓸 때 계속 떠올리는 기준들

README 정리를 하면서 자연스럽게 프로젝트 전반의 코드를 다시 훑게 됐고, 그때 재확인한 원칙들이 있다. 거창한 게 아니라 실제로 몸에 배어 있는 것들.

작은 커밋: 변경 단위를 잘게 유지하면 코드 리뷰도 쉽고 롤백도 명확하다. 이미 알고 있는 얘기지만 귀찮을 때 한 번에 몰아서 커밋하고 싶어진다. 그럴 때마다 나중에 git blame으로 추적하는 게 얼마나 힘든지를 기억한다.

문서 동기화: 코드가 바뀌면 관련 주석과 문서도 같이 업데이트. 이게 제일 흐지부지되기 쉬운 부분이다. 함수 이름 바꾸면서 위에 달린 JSDoc는 그대로 두는 경우, 로직 바꾸면서 README 예시 코드는 구버전인 경우. 둘 다 나중에 누군가를 혼란스럽게 만든다.

원칙	이유
단일 책임	하나의 함수/클래스는 하나의 역할만 - 테스트도, 교체도 쉬워짐
명시적 코드	영리한 코드보다 읽기 쉬운 코드 - 두 달 뒤에 내가 보는 코드
실패 우선 처리	happy path보다 에러 케이스 먼저 설계 - 실제 운영은 예외가 기본

코드를 쓸 때 머릿속에 세 가지 독자를 두는 편이다.

6개월 뒤의 나: 이 코드를 다시 봤을 때 맥락 없이도 이해할 수 있는가
다음 개발자: 나 말고 다른 사람이 봤을 때 어떻게 느낄까
새벽 3시의 온콜: 장애 상황에서 이 코드가 원인을 빠르게 파악하게 해주는가

특히 세 번째가 실제 운영 경험이 쌓일수록 무겁게 느껴진다. 잘 읽히는 코드와 디버그하기 좋은 코드는 겹치는 부분이 많지만 완전히 같지는 않다. 로그가 충분한지, 에러 메시지가 맥락을 담고 있는지, 어떤 값 때문에 실패했는지를 코드만 보고 추론할 수 있는지. 이런 것들이 새벽에 진짜 차이를 만든다.

좋은 코드의 기준	나쁜 코드의 신호
읽으면 의도가 바로 보임	주석 없으면 이해 불가
변경이 한 곳에만 영향	한 곳 바꾸면 여러 곳 수정 필요
테스트 작성이 자연스러움	테스트하려면 구조 바꿔야 함
에러 메시지가 원인을 담음	스택트레이스만 남기고 맥락 없음

README 하나 정리하는 데 생각보다 시간이 걸렸다. 근데 그 시간 동안 프로젝트 전체를 다시 보게 됐고, 고칠 것들이 눈에 보였음. PR 머지도 아니고 기능 추가도 아니라 당장 티가 안 나는 작업이지만, 이런 게 쌓여야 나중에 디버깅 시간이 줄고 새 팀원이 들어왔을 때 온보딩이 빠르다. 지금 10분 투자하면 나중에 1시간 아끼는 작업이라는 거, 해보면 안다.