※ 일본의 한 블로그 글을 번역한 것입니다. 오역 및 직역, 의역이 있을 수 있으며 틀린 내용은 지적해주시면 감사하겠습니다.
README이란?
README이란 리포지토리를 방문한 사람에게 "이 프로젝트는 무엇인지"를 알기 쉽게 전달하기 위하 설명서와 같은 것이다.
읽는 입장에서는 갑자기 소스 코드를 보는 것은 괴로우므로 먼저 README를 읽어 개요를 파악하는 것이 중요하다. 즉, 사람의 첫 인상이 중요하다면 GitHub 리포지토리의 README가 중요하다.
- 처음 리포지토리를 방문한 사람이 흥미를 가질지 아닐지
- 자신의 프로젝트를 써줄지 아닐지
는 README에 걸려있다고 해도 과언이 아니라는 것이다.
그렇다면 어떤 README가 사람을 끄는 멋진 REAME이란 무엇일까?
멋진 README란?
어떻게 써야 멋있는 README가 될까?
1. 알기 쉽게!
무엇보다도 알기 쉽게 쓰는 것이 중요하다. 맨 처음 리포지토리를 방문한 유저가 마주하는 README.
프로그램 코드와 동일한 마음가짐으로 작성하자.
2. 적당한 개행과 제목
README에만 한정된 얘기는 아니지만, 맺힘없이 줄줄이 이어지는 글을 계속 읽다보면 읽기 힘들어지는 데다 무엇이 적혀 있는 것인지 직감적으로 알기 어렵다.
GitHub의 README는, GitHub Flavored Markdown 이라고 불리며 GitHub의 독자 요소를 추가한 Markdown기법으로 작성할 필요가 있어, HTML의 <h1> ~ <h6> 태그와 같이 제목을 1~6 단계로 표현할 수 있다.
Markdown을 잘 다루어 보기 쉬운 문장을 쓰도록 유의하자. GitHub Flavored Markdown에 대한 상세한 내용은 GitHub Docs에 있다.
3. 뱃지 추가하기
README에는 아래와 같은 아이콘이 표시되어 있는 것을 본적이 있을 것이다.
이러한 것들은 뱃지라고 불리는 아이콘으로, 다양한 정보를 간략하고 알기 쉽게 표시할 수 있다.
예를 들어, 다음과 같은 정보를 README의 맨 앞에 표시하는 것으로 신뢰성이 올라간다!
- GitHub의 Star 수
- 합계 다운로드 수/월간 다운로드 수
- 라이센스
- 사용하고 있는 패키지의 버전
- 테스트를 통과한 코드라는 것(build가 가능한지 아닌지)
- 코드 커버리지율(소스코드의 테스트 비율)
어떻게 뱃지를 표시할까?
이러한 뱃지는 Github와 연계되어 있는 각 서비스를 통해서 표시할 수 있다. 아래에 몇 가지 뱃지 서비스를 기재해뒀으니 기회가 되면 확인해보길 바란다.
- shields.io
- GitHub의 프로젝트의 URL을 지정하면 다양한 정보가 자동적으로 획득하여 배치를 만들어준다.
- 색이나 형태 등 스타일의 커스터마이즈도 가능하다.
- 독자적인 뱃지도 만들 수 있다.
- travis-ci.org/
- JENKIN등, 빌드 결과를 표시
- coveralls.id
- 코드 커버리지율을 표시
4. 비주얼적인 요소 추가하기
문자만 있는 README는 보기에 즐겁지 않다. 프로젝트의 로고나 배너, 혹은 UI가 있다면 그 스크린 샷을 붙어 알기 쉽게 해도 좋으며 Demo를 Gif 파일로 만들어 표시하는 것도 읽는 입장에서는 알기 쉽다.
또한 위에 언급한 뱃지도 비주얼적인 요소 중 하나라고 할 수 있다.
실제로 써보자
그럼 실제로 무엇을 작성하면 좋을지 어떤 부분에서 유의해서 작성하면 좋을지 등 구체적인 작성법에 대해서 알아보자!
기본 항목
"리포지토리의 설명/개요", "목적", "사용법"은 기본 정보로 작성하자. 맨 처음 리포지토리르 방문한 유저의 입장에서 기본 정보가 굉장히 유익하다.
엔지니어를 위한 정보
"사용하고 있는 언어", "버전" 등 테크닉한 부분을 작성하면 좋다.
오픈 소스화되어 누구가가 사용하게 된다고 의식하고 있다면 컨트리뷰션 가이드와 같은 항목을 추가해도 좋을 것이다. 컨트리뷰션 가이드는 Vue.js 공식 사이트가 굉장히 참고하기 좋다고 생각한다. 어떤 흐름으로 컨트리뷰션하면 좋을지, 주의 항목등을 매우 알기 쉽게 기재되어 있으므로 자신의 리포지토리를 OSS화 하는 것을 검토하고 있다면 꼭 참고하길 바란다.
포트 폴리오용
그 중에서는 자신의 포트 폴리오의 일부로써 GitHub을 외부에 공개하고 있는 사람도 있을 것이다. "사용하고 있는 기술"은 물론이고, "시스템 구성도", "고집했던 부분" 등을 명확히 작성해 제대로 어필하도록 하자.
Web에 공개되어 있는 것에 대해서는 Heroku 나 Vercel의 호스팅 서비스를 사용하여 자신의 작품을 퍼블릭으로 공개하자! 그리고, GitHub에서도 GitHub Pages 이라는 기능을 사용하여 정적 콘텐츠의 호스팅도 가능하다.
정적 콘텐츠의 호스팅이라면, 개인적으로 추천하고 싶은 것은 surge이다. Nuxt.js의 HP에도 디플로이처의 후보 중 하나로 적혀있다. 정말 간단히 시간을 절약하여 호스팅할 수 있으므로 자신의 호스트 환경으로써 이용해보는 것을 추천한다.
그 외
기존에 리포지토리에 대해 알고 있는 유저의 입장에서는 업데이트 정보나 이후의 기능 확장 예정 등이 기쁜 정보이다. 항상 읽는 사람의 입장에서 쓰는 것을 잊지 말길!
README는 아니지만...
GitHub에는 About이라는 항목이 있다. 여기에서는 리포지토리의 짧은 설명문을 쓸 수 있다. 아래의 사진의 빨간 박스 안에 오른쪽위에 있는 톱니바퀴 아이콘을 클릭하면,
다음과 같은 팝업이 표시되므로 입력할 수 있다.
여기에 기재가 되어있으면, README를 읽지 않아도 리포지토리의 개요를 파악할 수 있게 된다. 바쁜 리쿠르터나 엔지니어에게는 기쁜 정보이다.
지금까지 언급했떤 README 작성할 항목을 리스트업 해두었으니 참고하길 바란다.
- 배지
- 프로젝트의 타이플
- 로고나 배너 이미지
- 프로젝트의 개요설명
- 서비스의 스크립션 이미지 or GIF 이미지(데모)
- 목차
- 필수조건
- 사용언어, 환경, 테크놀로지
- 시스템 구성도
- 사용법
- 설치방법
- 테스트 방법
- 디플로이 방법
- 고집했던 포인트
- 라이센스 정보
- 이후의 계획
참고자료
'IT > 기초 지식' 카테고리의 다른 글
| 변수 혹은 함수 영어 명명법 (0) | 2022.06.20 |
|---|---|
| [DB] RDB 데이터 베이스 설계 (0) | 2022.06.14 |
| [git] Github 팀 개발 메뉴얼 (0) | 2022.06.06 |
| [Figma] Figma에서 자주 사용하는 단축키 모음 (0) | 2022.06.03 |
| [Linux] 좋은 쉘 스크립트 쓰는 팁 (0) | 2022.05.26 |