GitHub README는 저장소를 처음 보는 사람이 프로젝트를 이해하고 실행하는 출발점입니다. 기능 목록만 적은 문서와 문제 해결 과정을 설명한 문서는 전달하는 정보가 다릅니다. 지원 직무와 프로젝트 성격에 맞게 구조를 고르세요.
기능 목록형의 장단점
‘로그인, 검색, 관리자 화면’처럼 구현 기능을 빠르게 보여 줍니다. 하지만 왜 만들었는지, 어떤 부분을 직접 담당했는지, 동작을 어떻게 확인할지는 빠지기 쉽습니다. 데모 화면과 코드 위치를 연결하면 단점을 줄일 수 있습니다.
문제 해결형의 장단점
사용자 문제, 선택한 설계, 구현, 테스트 결과, 제약을 순서대로 설명합니다. 면접에서 기술 선택 이유를 말하기 쉽지만 장황해질 수 있으므로 첫 화면에는 요약과 실행 링크를 놓고 상세 설명을 아래에 둡니다.
두 구조에 공통으로 필요한 것
설치·실행 방법, 필요한 환경, 테스트, 비밀 설정 방법, 사용한 자료의 출처를 적습니다. GitHub 공식 README 안내는 저장소 방문자에게 보이는 위치와 역할을 설명합니다. 비공개 키를 예제 설정 파일에 넣지 마세요.
선택 기준
작은 라이브러리라면 사용법이 앞에, 취업용 서비스 프로젝트라면 문제와 본인 기여가 앞에 오는 편이 자연스럽습니다. 무엇을 선택하든 처음 방문한 사람이 실행할 수 있는지 테스트하세요. 문장 예시는 GitHub README 예시에서 이어서 확인할 수 있습니다.