단순 소개 문서를 넘어서, 전달력을 고민한 README 작성기

 

MenuMate 프로젝트 README 링크

• 프로젝트 README
  https://github.com/kimin0401/MenuMate

 

서론

 

개인 프로젝트를 진행하면서 기능 구현에는 많은 시간을 들였지만, 정작 그 결과물을 어떻게 정리해서 보여줄지에 대해서는 갈피를 잡지 못하고 있었습니다.

특히 GitHub의 README는 단순한 설명 문서라고 했지만, 실제로는 프로젝트의 첫인상을 결정짓는 중요한 요소라는 것을 깨닫게 되었습니다.

이번 글에서는 MenuMate 프로젝트의 README를 작성하면서 고민했던 과정과, 단순한 기능 나열이 아닌 전달력을 높이기 위해 어떤 부분을 개선했는지 정리해보려고 합니다.

 

문제 상황

처음 README를 작성할 때는 아래와 같은 고민이 있었습니다.

• 무엇을 어디까지 작성해야 할지 기준이 없었다
• 기술 스택을 단순히 나열하는 것이 맞는지 고민됐다
• README가 길어질수록 오히려 읽기 어려워지는 문제가 있었다

결과적으로 README 초안은 "기능은 있지만 읽히지 않는 문서"였습니다.

 

해결과정

1. 구조부터 설계하기

가장 먼저 한 일은 내용을 쓰는 것이 아니라 목차를 먼저 잡는 것이었습니다.

프로젝트 소개
주요 기능
기술 스택
폴더 구조
설치 및 실행 방법
트러블슈팅

구조를 먼저 잡고 나니, 어떤 내용을 어디에 써야 할지 명확해졌습니다.

 

2. 기능 설명을 "사용자 경험" 중심으로 변경

처음에는 기능을 이렇게 작성했습니다.

• 검색 기능
• 상세 페이지 기능

하지만 이렇게 작성하면 프로젝트의 차별점이 드러나지 않는다는 것을 느꼈습니다.

그래서 다음과 같이 수정했습니다.

• 검색 기능 -> 사용자 의도 기반으로 동작하도록 설계
• URL 상태 관리 -> 뒤로가기 시에도 검색 결과 유지

단순 기능이 아니라 사용자 경험을 어떻게 개선했는지 중심으로 작성했습니다.

 

3. 기술 스택을 "왜 사용했는지"로 설명

기술 스택도 처음에는 단순히 나열하는 방식이었습니다.

기술 스택
Next.js
TypeScript
Tailwind CSS

하지만 이 방식은 큰 의미가 없다고 판단하고 다음과 같은 방식으로 변경했습니다.

• Next.js -> 라우팅과 서버 컴포넌트 구조 경험을 위해
• TypeScript -> 외부 API 데이터 안정성 확보
• TanStack Query -> 서버 상태 캐싱을 통한 UX 개선

기술을 단순히 "사용했다"가 아니라 "왜 선택했는가"를 설명하는 방향으로 바꿨습니다.

 

4. 트러블슈팅을 선별해서 정리

블로그에 정리해둔 문제 해결 경험이 여러개 있었지만, README에는 모두 넣지 않았습니다.

대신 기준을 세웠습니다.

• 단순 오류 해결 경험은 제외
• 구조/설계/UX 개선 경험은 채택

그래서 최종적으로 아래 3가지만 남겼습니다.

• 상태 관리 -> 캐싱 구조로 리팩토링
• API 500에러 -> debounce 적용
• App Router 구조 오해 -> build 오류 해결

README에 트러블슈팅 경험을 단순히 많이 넣기보다 유의미한 핵심 경험들을 정리해 넣는 것이 좋다는 것을 느꼈습니다.

 

5. 이미지와 경로 문제 해결

README에 스크린샷을 넣는 과정에서도 문제가 있었습니다.

• 이미지가 보이지 않는 문제 발생
• public 경로와 GitHub 경로를 혼동

이 과정을 통해 README는 Next.js 기준이 아니라 "GitHub 기준 경로"로 동작한다는 것을 배웠습니다.

그래서 docs/images 폴더를 따로 만들어 관리했습니다.

 

결과

README를 수정한 이후에는 다음과 같은 변화가 있었습니다.

• 구조가 명확해져서 읽기 쉬워짐
• 기능보다 "의도"가 잘 전달됨
• 프로젝트 전체 흐름을 한눈에 파악 가능
• 트러블슈팅을 통해 개발 경험이 드러남

 

느낀 점

이번 작업을 통해 가장 크게 느낀 점은 다음과 같습니다.

• README는 단순 문서가 아니라 프로젝트의 설계 결과물이다
• 기능 구현보다 그걸 어떻게 설명하느냐도 중요하다
• 좋은 README는 "읽히는 코드"만큼 가치가 있다