Original article: How to Write a Good README File for Your GitHub Project

처음 깃허브를 알게 되었을 때 저는 깃허브가 무엇인지 전혀 모르는 상태였습니다. 실은, 개발자라면 코드를 올리는 곳이 있어야 한다는 얘기를 듣고 깃허브 계정을 만들게 되었습니다.

오랜 기간 동안 입문자였던 저는 깃허브로 아무것도 하지 않았습니다. 하지만 기술에 대한 열정이 생기면서 다른 개발자들의 계정을 팔로우하고 깃허브에 올라온 그들의 작업물들을 보기 시작했습니다. 그리고 그들의 공통점을 알게 되었습니다. 모두 멋진 프로젝트를 하고 오픈소스에 기여하며 구체적인 리드미 파일이 있다는 점이었죠.

그래서 리드미 파일에 대한 관심이 커지기 시작했고, 제 프로젝트에도 넣어볼까 생각하게 되었습니다. 사실 리드미 파일을 어떻게 써야 하는지도 모르는 채로 급하게 작성했습니다. 솔직히 말씀드리면 너무 형편없었죠. 여기에서 확인해 보실 수 있습니다.

꽤 오랫동안 비슷한 상태였습니다. 하지만 계속 연습하고 공부하면서 이렇게 나아진 리드미 문서는 프로젝트에 더 몰입하고 다른 개발자들의 참여를 유도하는 데 도움이 되었습니다.

좋은 리드미는 깃허브에 작업물을 올리는 수많은 개발자들 사이에서 자신을 돋보일 수 있게 해주는 중요한 수단입니다.

이 글에서는 좋은 리드미 파일이란 무엇이며, 어떻게 작성해야 하는지에 대해서 배울 것입니다. 먼저 리드미 파일의 의미를 이해해 봅시다.

리드미 파일이란?

간단히 말해서, 리드미 파일은 사람들에게 여러분이 작업한 프로젝트에 대해 구체적인 설명을 제공하는 가이드라고 보시면 됩니다.

프로젝트를 어떻게 사용할 수 있는지에 대한 가이드 문서라고도 설명할 수 있겠네요. 일반적으로 리드미 파일은 프로젝트 설치 방법과 실행 방법을 명시합니다.

여러분이 개발자로서 리드미를 작성하며 프로젝트를 문서화할 줄 아는 것이 중요한 이유는 다음과 같습니다:

  • 리드미는 여러분의 프로젝트에서 가장 먼저 보이는 페이지이기 때문에 간단하면서도 구체적이어야 합니다.

  • 리드미는 많은 프로젝트들 사이에서 여러분의 프로젝트를 돋보이게 합니다. 여러분의 프로젝트 또한 훌륭해야 한다는 점도 잊지 마세요.

  • 리드미는 프로젝트가 무엇을 어떻게 전달하고 싶은지에 대해 여러분이 집중할 수 있게 도와줍니다.

  • 리드미를 쓰면 글쓰기 능력이 향상됩니다. 프리드리히 니체(Friedrich Nietzsche)는 다음과 같이 말했습니다:

훌륭한 작가는 자신의 생각뿐만 아니라 친구들의 생각까지 마음에 품고 있다.

프로젝트를 할 때, 다른 개발자들이 여러분의 코드를 이해해야 한다는 점을 염두에 두어야 합니다. 그래서 추가적인 가이드를 포함하는 것이 큰 도움이 될 것입니다.

예를 들어, 위에서 공유했던 제 첫 번째 프로젝트의 리드미는 형편없었죠. 프로젝트 자체는 훌륭했지만 초심자가 제 레포지토리를 클론하면 정확히 무엇이 일어나는지 이해하기 힘들었을 것입니다. 그 파일에 바이러스가 있는지 누가 알겠어요.

깃허브에 이런 프로젝트를 올리면, 얼마나 훌륭한지에 상관없이 다른 개발자들은 잘 쓰여진 리드미가 없으면 그 프로젝트에 대해 알아보거나 작업하고 싶지 않을 것입니다.

이제 이 프로젝트를 살펴봅시다. 이번엔 이게 무슨 프로젝트인지, 어떤 내용을 포함하고 있는지, 이 프로젝트를 이용하거나 기여하기 위해선 어떻게 해야 하는지에 대해 알아볼 수 있습니다.

이게 바로 잘 쓰인 리드미의 위력이며, 이런 리드미는 여러분의 프로젝트를 변화시킬 수 있습니다.

그럼 이제 어떻게 작성해야 하는지에 대해 알아보겠습니다.

좋은 리드미를 작성하는 방법 - 단계별 가이드

가장 주의해야 할 점은 좋은 리드미를 작성하는 방법은 한 가지가 아니라는 점입니다. 하지만 굉장히 잘못된 방법은 하나 있는데요, 그것은 리드미를 전혀 작성하지 않는 것입니다.

다양한 리드미 파일을 찾아보고 연구해 본 결과, 제가 발견한 가장 확실한 방법이 있습니다. 이것을 공유드리고자 합니다. 제가 종종 스스로 되뇌이는 것처럼 말이죠:

매일이 학습의 날이다.

여러분이 커리어를 쌓아나가면서, 리드미를 잘 쓰고 발전시킬 수 있는 여러분만의 방식을 찾아 나가게 될 것입니다. 아마 여러분은 자신만의 독특한 가이드를 만들게 될 수도 있습니다.

본격적으로 시작하기 전에 주의해야 할 점이 있습니다. 프로젝트의 리드미를 작성할 때, 프로젝트의 무엇을, 왜, 어떻게에 대해서 답해야 한다는 점입니다.

이것을 도와줄 가이드 질문들이 있습니다:

  • 동기가 무엇이었나요?
  • 왜 이 프로젝트를 기획했나요?
  • 이 프로젝트는 어떤 문제를 해결하나요?
  • 이 프로젝트를 통해 무엇을 배우셨나요?
  • 이 프로젝트의 특징은 무엇인가요?
    만약 프로젝트의 특징이 너무 많다면, '특징' 섹션을 추가해서 이곳에 나열하세요.

리드미에 들어가야 하는 내용

1. 프로젝트명

먼저 프로젝트의 이름입니다. 한 문장으로 전체 프로젝트를 설명하고 사람들이 프로젝트의 주 목표가 무엇인지 이해할 수 있게 도와줍니다.

2. 프로젝트 설명

이 부분은 많은 개발자들이 간과하는 프로젝트의 주요 요소입니다.

설명은 프로젝트에서 굉장히 중요한 부분을 차지합니다. 잘 다듬어진 설명을 통해 미래의 인사 담당자뿐만 아니라 다른 개발자들에게도 여러분의 작업물을 자랑할 수 있습니다.

리드미에서 설명의 질은 좋은 프로젝트와 그렇지 못한 프로젝트를 구분 짓습니다. 잘 쓰인 리드미를 통해 다음과 같은 내용을 설명하고 소개할 수 있습니다.

  • 여러분의 애플리케이션이 무엇을 하는지,
  • 왜 그 기술을 사용했는지,
  • 여러분이 당면했던 문제나 나중에 추가하고 싶은 기능이 무엇인지

3. 목차 (선택)

만약 리드미가 너무 길다면, 사용자들이 다른 섹션으로 쉽게 이동할 수 있게 목차를 만들 수도 있습니다. 목차를 통해 독자들이 쉽게 프로젝트를 살펴볼 수 있을 것입니다.

4. 프로젝트 설치 및 실행 방법

만약 사용자가 따로 설치하거나 포스기와 같은 기계에서 실행해야 하는 프로젝트를 작업하고 있다면, 프로젝트를 설치할 수 있는 방법과 필요한 경우 dependencies를 포함해 작성해야 합니다.

개발 환경을 세팅하고 실행할 수 있는 단계적인 설명을 제공하세요.

5. 프로젝트 사용 방법

사용자/기여자들이 프로젝트를 이용할 수 있는 방법과 예시를 작성하세요. 예상 문제에 대해 항상 참고할 수 있는 곳을 마련함으로써 그들이 문제에 직면했을 때 쉽게 해결할 수 있을 것입니다.

프로젝트 실행 예시 화면의 스크린샷과 같은 시각 자료를 사용할 수도 있고 프로젝트에서 사용된 구조나 디자인 원칙을 추가할 수 있습니다.

프로젝트에 비밀번호나 유저 네임이 필요한 경우 계정을 적어두는 것도 좋은 방법입니다.

6. 팀원 및 참고 자료

만약 팀이나 조직 단위로 작업한 프로젝트라면 팀원들을 같이 기재하세요. 팀원들의 깃허브 프로필과 SNS 링크도 연결해야 합니다.

사용자가 프로젝트를 설치하는 데 도움을 줄 수 있는 튜토리얼이나 자료를 참고했다면 그런 링크도 같이 첨부해야 합니다.

이렇게 함으로써 감사를 표현함과 동시에 사람들이 프로젝트의 첫 번째 사본을 얻을 수 있습니다.

7. 라이센스

대부분의 리드미에서 라이센스는 가장 마지막으로 고려되는 부분입니다. 라이센스를 보고 다른 개발자들은 여러분의 프로젝트로 무엇을 할 수 있고 무엇을 할 수 없는지 알 수 있습니다.

우리는 작업하고 있는 프로젝트의 종류에 따라 다른 라이센스를 가지고 있습니다. 여러분이 고르는 라이센스에 따라서 프로젝트의 기여가 달라질 수 있습니다.

가장 흔한 라이센스는 다른 사람들이 여러분의 코드를 수정할 수 있고 상업적인 용도로 사용할 수 있는 GPL 라이센스입니다. 라이센스를 고를 때 도움을 받고 싶다면, 이 링크를 확인해 보세요: https://choosealicense.com/

지금까지 좋은 리드미를 위한 최소한의 요건을 살펴보았습니다. 하지만 눈길을 더 사로잡고 상호적인 리드미를 만들고 싶다면 다음 내용을 추가해 볼 수 있습니다.

추가적인 부분

8. 뱃지

뱃지는 꼭 필요하진 않지만, 뱃지를 사용하면 다른 개발자들이 프로젝트에 대해 쉽게 알 수 있습니다.

이 섹션이 있으면 중요한 툴로 연결해 주거나 포크, 기여자, 오픈된 이슈 등 여러분의 프로젝트와 관련된 간단한 통계를 보여줄 수도 있습니다.

다음 사진은 뱃지 사용 방법을 보여주는 제 프로젝트의 스크린샷입니다:
뱃지 캡쳐

이 부분의 좋은 점은 자동으로 업데이트된다는 점입니다.

어디서 뱃지를 받는지 모르시겠다고요? shields.io에서 제공하는 뱃지를 확인해 보세요. 바로 사용할 수 있는 수많은 뱃지가 있습니다. 지금은 다 이해할 수 없어도 시간이 지나면 다 알게 될 것입니다.

9. 프로젝트에 기여하는 방법

이 부분은 다른 개발자들이 기여할 수 있는 오픈 소스 프로젝트를 작업하고 있는 경우라면 가장 유용한 섹션일 것입니다. 여러분은 아마 다른 개발자들이 프로젝트에 어떻게 기여할 수 있는지에 대한 가이드라인을 추가하고 싶을 것입니다.

또한 향후 충돌을 막기 위해서 오픈소스 프로젝트에 사용되는 라이센스가 올바른 것인지 확인하는 것이 중요합니다. 기여 가이드라인을 추가하면 큰 도움이 되겠죠.

가장 잘 알려진 가이드라인으로는 Contributor Covenant와 기여 가이드가 있습니다. 프로젝트의 규칙을 정할 때 이 문서들이 도움이 될 것입니다.

10. 테스트

더 나아가 애플리케이션의 테스트를 위해 예제 코드와 실행 방식을 작성하세요.

이렇게 함으로써 여러분의 프로젝트가 문제없이 작동할 것이라는 확신과 자신감을 보여줄 수 있고, 다른 사람들 또한 확신을 갖게 될 것입니다.

참고사항

다음은 여러분이 리드미를 작성할 때 참고하면 좋을만한 내용들입니다:

  • 내용을 최신으로 유지하기- 항상 파일을 최신 상태로 유지하는 것이 좋습니다. 변경 사항이 있는 경우 필요한 부분의 리드미를 꼭 업데이트해두세요.
  • 언어 선택하기- 우린 모두 다른 지역에서 왔고 서로 다른 언어를 사용합니다. 그렇다고 코드를 번역해야 한다는 뜻은 아닙니다. 영어는 글로벌하게 사용되므로 영어로만 리드미를 작성하면 됩니다. 만약 타깃층이 영어에 친숙하지 않다면 번역기를 사용할 수 있겠죠.

마무리

리드미를 고쳐나가거나 첫 번째 리드미를 작성하기 위해 필요한 모든 내용을 살펴보았습니다.

이제 저는 여러분이 기존 프로젝트나 다음 프로젝트에서 프로젝트를 더 돋보이게 하기 위한 상호적이면서도 유익한 가이드를 추가할 수 있을 것이라고 확신합니다.

프로젝트에 자동으로 리드미를 생성해 주는 도구가 많긴 하지만, 자동화하기 전에 직접 먼저 만들어 보는 것이 좋습니다. 자동화 도구들을 확인하고 싶으시다면 다음 링크를 참고해 보세요:

여기까지 읽어주셨다면 진심으로 감사드립니다. 이 글이 재미있었거나 도움이 되었다면 다른 개발자들도 프로젝트를 보완할 수 있게 공유해주세요.

여러분이 새로 만든 리드미 파일도 보고 싶네요. 다음 링크를 통해 꼭 공유해 주세요.

Twitter | YouTube | LinkedIn | GitHub로 소통해요.

여러분의 소중한 의견도 공유해 주세요. 솔직한 피드백도 환영합니다!

즐거운 코딩하세요❤