Github README 작성에 대해
다음의 포스트를 참고하여 작성하였습니다.
How to Write a Good README File for Your GitHub Project, (2021.11.13)
0. README
Github를 사용할 경우 다른 사람들이 프로젝트를 잘 이해할 수 있도록 좋은 프로젝트 문서를 작성해야한다.
보통 많은 사람들이 Github를 입문할 때 README파일에 대해 잘 알지 못하고 시작한다.
(그냥 뭐 다른 사람들의 프로젝트에 있는 멋진 문서 정도?? 나는 그렇게 생각했다.)
원글에 내용처럼 나도 점차 개발에 대한 열정이 커지면서 다양한 유저들을 팔로우하기 시작했다.
멋있는 개발자들은 모두 아름다운 프로젝트를 가지고 있고, 유명한 오픈소스에 기여했다는 공통점이 있었다
또한 그들의 아름다운 프로젝트에는 자세한 README 파일이 있었다.
나도 README를 잘 써보기로 결심했다.
1. 왜 README를 잘써야하나
README파일은 저장소에 올라와있는 프로젝트에 대한 자세한 안내를 해주는 가이드 문서이다.
사실 모든 문서가 그렇지만 잘 쓰려고 하기 위해서는 많은 시간 투자가 필요하기 마련이다.
그런데 프로젝트 코드가 아닌 README 파일 작성에 그렇게 시간을 투자해야하는 이유가 있을까?
- 좋은 README는 나의 프로젝트가 타 프로젝트와 차별화를 주는데 도움이 된다. 프로젝트 자체만큼 README도 좋아야한다.
- 프로젝트를 접할 때 가장 먼저 보게 되는 얼굴이므로 간단하게 그러면서도 상세하게 작성해야한다.
- 프로젝트가 제공해야 하는 것과 방식에 대해 한 번 더 알아가게되며 이는 큰 도움이 된다.
README파일을 작성할 때에는 내가 아닌 다른 개발자가 이해해야 한다는 점을 염두해야한다.
아무리 멋진 프로젝트여도 README가 없다면 얼마나 많은 시간을 들여 프로젝트를 했더라도 이해할 수 없고 알지 못할 것이다.
2. 좋은 README파일을 쓰는 방법?
좋은 README를 구성하는 정답은 없다. 하지만 오답은 있는 것 같다.
README에 들어가야할 내용을 정해놓으면 쓰는데 도움이 된다.
1) 프로젝트 제목
전체 프로젝트를 한 문장으로 설명하고 사람들이 이 프로젝트의 주요 목표가 무엇인지 이해할 수 있도록 도와준다.
제목은 프로젝트의 성격을 보여주는 얼굴이다.
2) 프로젝트 설명
잘 작성된 설명을 통해 다른 개발자와 추후의 채용담당자에게 나의 능력을 어필할 수 있다. 많은 개발자들이 간과하는 내용이지만, 그렇기에 좋은 설명 내용은 다른 개발자 사이에서도 눈에 띄는데 큰 도움이 될 것이다.
- 어플리케이션의 동작
- 사용한 기술의 선택 이유
- 이슈 혹은 향후 계획
3) 목차(선택 사항)
내용이 너무 길 경우에는 사용자가 필요한 것으로 바로 점프할 수 있도록 상단에 목차를 추가해주는 것이 좋다.
4) 프로젝트 설치 방법
설치가 필요한 경우 프로젝트를 설치하는 방법을 설명해주면 좋다. 혹은 개발 환경 구축에 대한 내용도 상황에 따라 제공하면 좋다.
5) 프로젝트 사용 방법
프로젝트를 사용할 수 있도록 설명이나 example을 제공한다. 이럴 경우 문제 발생 시 쉽게 대처할 수 있다.
실행 중인 프로젝트의 스크린샷 등을 포함하는 것도 좋은 방법이다.
6) 명단(credit)
팀 혹은 단체로 프로젝트에 참여했다면 공동 작업자/팀 구성원을 나열하고 그들의 Github 프로필에 대한 링크를 포함한다.
이 명단은 추후 프로젝트 배포 시에 감사를 표시하기 위한 링크로 사용될 수 있다.
7) License
다른 개발자가 프로젝트에서 할 수 있는 것과 할 수 없는 것을 알 수 있게된다.
그 외에도 뱃지나 프로젝트 기여 방법, 테스트 내용 등을 포함할 수 있습니다.
3. 마지막
README는 프로젝트 성격에 따라서 내용과 형식이 달라질 것이다.
멋진 개발자들의 아름다운 README파일들을 많이 살펴보면서 나의 README스타일을 만들어가면 좋을 것 같다.