README 작성 가이드

 

 

README란?

---

readme란 프로젝트에 대한 간단한 설명을 담고 있는 문서이다. 일반적으로 git에서 특정 레포지토리에 들어가면 가장 먼저 보이는 main page가 바로 readme이다. 이런 readme 파일은 일반적으로 markdown 문법으로 작성된다.(확장자는 md) 쉽게 말해 readme를 작성한다는 것은 구현한 프로젝트를 문서화하는 작업이다.

그렇다면 readme 파일은 도대체 왜 작성해야 할까?

• 나를 위해 - 시간이 지나면 자신이 작성한 코드도 다시 읽어보아야 이해가 간다. 이처럼 나중에 자신이 보았을 때에도 쉽게 이해할 수 있도록 readme를 작성해두면 도움이 된다.

• 함께 작업하는 동료를 위해 - 협업을 할 때 동료에게 내가 작성한 readme는 좋은 지침서가 될 수 있다.

• 다른 사용자들을 위해 - 본인이 만약 오픈소스나 어떤 API를 만든다면 이를 사용하기 위한 사람들에게도 readme는 지침서가 된다.

위와 같은 이유로 readme를 작성한다. 귀찮지만 앞으로는 조금 더 신경써서 작성해야겠다.

 

readme에는 어떠한 내용을 작성해야 할까?

---

딱히 고정된 양식이 있는 것은 아니다. 다른 사람들의 레포지토리를 보아도 양식이 조금씩 다르다. 어떤 분야의 프로젝트에 대한 개발인지에 따라 필요한 내용이 다르기 때문이다. 여러 가이드와 레포지토리들의 readme를 보고 공통적인 사항들과 내가 작업을 하며 있었으면 좋겠다고 생각한 것들을 추합하여 어떠한 내용이 들어가야 하는지 정리해보려고 한다.

Description

프로젝트에 대한 간단한 설명을 기술한다. 어떠한 일을 수행하기 위한 프로젝트인지, 어떠한 서비스를 위한 것인지를 작성하면 된다. 너무 길게 작성하기 보단 간결하고 명료하게 작성하는 것이 좋다. 프로젝트의 가치를 전달하는 것도 좋다.

Environment

실행환경에 대해 작성하면 된다. OS나 컴파일러 혹은 Hardware와 관련된 환경을 작성하면 된다. Multicore 환경에서 돌아가는 프로그램이라면 CPU나 RAM 같은 것들을 작성해도 좋다.

Prerequisite

작성한 코드를 실행하기 전에 설치해야할 pakage나 의존성이 걸리는 문제들을 설명하면 된다.

Files

이 항목은 내가 추가한 것이다. 중요한 코드 파일들 몇 개를 대상으로 해당 파일이 어떠한 역할을 하는 파일인지를 간단히 설명해주면 전반적인 맥락을 파악하기에 좋을 것 같아 추가하였다.

Usage

작성한 코드를 어떻게 실행해야 하는지에 대한 가이드라인이다. Usage Example을 함께 작성하면 좋다.

이 외에도 라이센스, contributing 같은 것들도 있지만 처음부터 readme를 복잡하게 작성하기 보단 프로젝트의 규모가 커지면서 디테일하게 추가하며 다듬는 것이 좋다.

 

간단한 markdown 문법 예시

---

readme를 작성하기 위해 필요한 간단한 markdown 문법을 소개한다. 해당 내용은 동빈나님의 유튜브 채널과 Git 레포지토리를 참고하였다.

## 깃 튜토리얼

소스코드 블록은 다음과 같이 작성할 수 있습니다.

```c
#include <stdio.h>

int main(void) {
  printf("Hello World!");
  return 0;
}
```

링크는 다음과 같이 작성할 수 있습니다.

[블로그 주소](https://blog.naver.com/ndb796)

순서 없는 목록은 다음과 같이 작성할 수 있습니다.

* 깃 튜토리얼
  * 깃 Clone
  * 깃 Pull
  * 깃 Commit
    * 깃 Commit 1)
    * 깃 Commit 2)

인용 구문은 다음과 같이 작성할 수 있습니다.

> '공부합시다.' - 나동빈 - 

테이블은 다음과 같이 작성할 수 있습니다.

이름|영어|정보|수학
---|---|---|---|
나동빈|98점|87점|100점|
홍길동|97점|78점|93점|
이순신|89점|93점|97점|

강조는 다음과 같이 할 수 있습니다.

**치킨** 먹다가 ~~두드리기~~났어요. ㅠㅠ

 

위와 같이 readme를 작성하면 아래와 같이 나온다. Git에서 미리보기 기능을 제공하니 이를 바탕으로 직접 작성하며 수정하면 될 것이다.

 

 

추가적으로 참고하면 좋을 듯한 사이트가 있어 첨부한다.

github.com/ByungJun25/Wiki/blob/master/Markdown/Example.md#%EA%B0%9C%ED%96%89new-line