git repository의 README를 쓰다가 의문이 들었다.
누가 먼저 쓸 생각을 했을까?
한국인에게 컴퓨터 설치파일을 까는 건 다 해봤을 거라고 생각한다. 그게 게임일 수도 있고 unzip프로그램, MS의 office등… 어릴때 설치해본 프로그램 중 기억에 많이 남는건 곰플레이어가 아닐까 싶다. 기억은 안나지만 아마 곰플레이어에도 README가 있었을 것이다. 웹뿐만 아니라 대부분의 소프트웨어에는 이런 README가 있다. README는 정확히는 밝혀지지 않았으나 1970년대부터 쓰였다고 한다. 역사가 깊은만큼 어느정도 README의 틀이 정해져 있다. 대부분 README는 주로 프로젝트의 루트 디렉토리에 위치하며, 프로젝트에 대한 기본 정보, 사용 방법, 설치 지침 등을 제공하는 텍스트 파일이거나 마크다운 파일이다. 프로젝트를 사용하는 사람들이 초기에 참고할 수 있는 중요한 문서이기 때문에 README를 깔끔하게 쓸 필요가 있다.
웹개발자인 나의 경우에는 주로 프로젝트의 git에서 Markdown 형태로 되어있는 README를 작성한다. README를 쓰면서 작성하는법을 기록으로 남겨놓으면 어떨까 싶어서 글을 쓴다. README에 어떤 내용이 들어가면 좋은지? 프로젝트별로 어떤 내용이 필요한지 주관적으로 고민한 것을 작성해본다. README는 회사마다, 사람마다, 프로젝트별로 작성 방법이 다르다. 본 포스팅은 나의 방법이다.
우선적으로 README를 하려면 꾸밀 줄 알아야한다. 하지만 다 외우고 있을 필요는 없다 요새는 마크다운을 위한 소프트웨어들이 다 잘되어 있다. 그래도정리가 되어있으면 쓰기 편하기에 정리는 했다.
그리고 README를 쓰기 위해서는 무엇이 필요할까? 나는 README를 쓰기 위해서는 그 프로젝트의 성격, 목적을 알아야 한다 생각한다. 그리고 내가 주로 쓰는 README는 크게 두가지 성격이다. 오픈소스 또는 회사의 프로젝트, 취업 또는 이직용 포트폴리오성 프로젝트
포트폴리오용 프로젝트
포트폴리오용 README를 누가 읽어주었으면 하는가? 대부분의 사람들은 입사담당자가 읽어줬으면 할 것이다. 그렇다면 그들이 필요한 정보를 제공하면 된다. 이 경우에는 당신이 무엇을 했는 지, 이 프로젝트는 어떤 프로젝트인지, 왜 이런 생각을 가지고 개발을 했는 지 어떤 skills를 사용하였는지가 이소프트웨어가 동작하는 법보다 더 궁금할 것이다.
프로젝트 개요
프로젝트의 목적과 목표를 간단하게 소개한다 만약 있다면 왜 이러한 프로젝트를 선택했는 지도 작성해주면 좋다. 그리고 프로젝트를 진행하면서 어떤 방식으로 업무 공유했는지도 쓰면 좋을 것 같다.
기술 스택
서류심사의 경우, 담당자가 개발자가 아닌 경우도 많은 것 같다. 그들은 당신이 어떤 기술을 썼는지 모르는 경우가 많다. 그런 경우가 아니라도 많은 지원자의 서류를 확인해야 하는 경우 눈에 들어오게 작성해놓으면 유리하다.
아키텍처
프로젝트의 아키텍처를 그림이나 사진으로 표현하여 첨부한다.
주요 기능
프로젝트의 핵심 기능을 강조하고 웹의 경우 서버 배포까지 했으면 url을, 아닌 경우 사진이나 그림으로 설명한다.
기여도와 역할
스크럼이나 업무 분담을 한 방식을 표현해준다.
결과 및 성과
프로젝트의 결과물과 어떤 문제를 해결했는지, 어떤 성과를 달성했는지 강조한다. 정량적 수치가 있으면 더 좋다.
그외
향후 계획, 프로젝트를 통해 배운점, 프로젝트에서 문제점을 해결한 과정, 프로젝트의 개선점, 확장성등을 이야기 해도 된다.
업무용 프로젝트
프로젝트 소개
프로젝트의 목적과 목표를 설명한다.
설치 및 시작 가이드
프로젝트를 사용하기 위한 간단한 설치 및 시작 가이드를 제공하고 필수 의존성이 있다면 함께 설명한다.
사용 예제:
프로젝트의 주요기능을 설명하고 사용예제를 코드블록을 이용하여 작성한다.
기능 목록 및 문서:
내부 문서들도 첨부해놓는다. (디자인문서, API문서 등 이 프로젝트 이용에 참고가 될만한 문서)
뱃지
Travis CI, Codecov 등과 같은 뱃지를 사용하여 프로젝트의 상태를 시각적으로 표시하면 좀 더 있어보인다…
버전 기록
프로젝트의 버전 기록과 변경 사항을 간략하게 작성한다.
그 외 오픈 소스의 경우
FAQ나 기여하는 방법, 라이센스 정보, 연락처, 기여자, 후원자등을 작성하는 경우가 많다.
그냥 이대로 끝내기에는 아쉬우니 nest js 의 README를 읽어보면
프로젝트 설명, 개요, 철학, 시작하는 법, 질문, 이슈, 후원, 연락처, 라이센스가 있다.
그러면 react의 경우는 뭐가 있을까?
프로젝트 설명, 설치 방법, 문서, 동작 예시, 기여, 이슈, 라이선스 등이 있다.
README 작성은 엄청 귀찮다. 하지만 react나 nest와 같이 README는 다 비슷한맥락으로 작성된다. 그러니 이 말은 README는 기본만 지켜도 된다는 것이다. 너무 열심히 README에 최선을 다 할 필요는 없다고 생각한다. 하지만 기본은 지켜야한다.
