Github README.md 작성법

README란?

프로젝트의 설명 뿐만이 아닌 사용방법, LICENSE, 설치법과 같은 설명이 필요한 부분에 대해서 기술하는 파일이다. 주로 Github Repository의 Main Page로서 작동한다.

왜 README를 써야할까?

어떤 프로그램을 사용하기 위해 Github repository를 들어가 봤을 때, 만약 README가 없는 repository라면 과연 그 프로그램을 사용할까? 대부분의 사람들은 사용하지 않을 것이다.

우리는 프로젝트에 대해 처음부터 알고 있지 않기 때문에, 사용법을 익혀야 한다. 때로는 프로젝트가 너무 오래되어서 코드를 작성한 본인조차 어떤 문제점이 있는지, 어떻게 사용하는지, 어떤 기능이 있는지 아무것도 모를 경우도 많다.

이러한 경우를 고려해본다면, README는 프로젝트를 파악하기에 아주 유용한 수단이 될 것이다.

README 구조

1. Project명 (Header 1)

   1. 해당 프로젝트가 어떤 프로젝트인지 소개

2. 프로젝트 정보

   1. 설치 (Header 2)
      1. Getting Started 또는 Installation
   2. 사용 방법 (Header 2)
   3. 이 부분에 대해 작성할때는 최대한 간결한 설명이 될 수 있도록 하자
   4. 또한 다음에 대해 설명할 수 있어야 할 것이다.
      1. 어떤 Step을 밟아야 할까?
      2. 프로그램을 사용하기 위해 어떤 패키지/프로그램이 설치/설정 되어있어야 할까?
      3. 프로젝트에 대해 바로 이해하기에 어려운 점은 어떤 것들이 있을까?

3. Contribute

   1. 다른사람들이 코드에 contribute하기 쉽도록 설명하는 부분을 추가하도록 하자!
   2. 이 부분을 위해서 LICENSE를 기입해야할 필요가 있다.

      1. 어떤 LICENSE를 사용할지 모르면 아래 사이트를 참조하면 쉽게 선택할 수 있다!

         https://choosealicense.com/
         

4. Code Status

   1. Shield라고 불리는 것을 사용해보자
      1. [build | passing]과 같은 정보를 줄 수있다.
   2. 일단 막 README를 작성한다면 이 부분에 대해서는 크게 신경쓰지말자
      1. 프로젝트가 커질수록 도움이 되는 부분

5. 주의점

   1. README를 처음부터 너무 복잡하게 작성하지 말자
      1. 코드를 작성하면서 프로젝트가 커질수록 README를 디테일하게 작성할 수 있도록 하는편이 바람직하다

Markdown(마크다운) 작성 가이드

• 굵은 글씨: 강조하고 싶은 단어의 앞뒤에 **을 붙여준다.
• 기울임 글씨: 강조하고 싶은 단어의 앞뒤에 _를 붙여준다.
• 코드 글씨: 강조하고 싶은 문장의 앞뒤에 `(키보드에서 숫자1의 왼쪽에 있는 키)를 붙여준다.
• 타이틀 글씨: 글을 작성하기 전 맨 첫 문장에 #을 원하는 만큼 붙여준다. (Header 1 ~ Header 6)

원하는 문법이 없을 경우, HTML는 좋은 선택이 될 것이다. 모든 markdown파일은 .md 확장자로 저장한다.