README 파일 작성하기

Udacity - “Writing READMEs” 강의 수강 후기

들어가며

나는 개발하는 과정은 좋아하지만, 개발 전/후의 문서화 과정을 귀찮아하는 편이다.

하지만 “귀찮다 = 어렵다”라고 했다! (실제로 글을 쓰는 것을 어려워하기에, 맞는 말이다)

그래서 개발 문서의 First Step인 README.md를 잘 작성하는 것부터 시작해보기로 했다.

마침 Udacity에 “Writing READMEs” 강의가 있다는 것을 알고 있었고, 수강 후 후기를 정리하였다.

Why.(문서화는 왜 중요한가?)

“코드를 이해시키기 위해서.”

내가 작성한 코드를 미래의 나 & 동료 & 사용자가 이해할 수 있도록 도와주는 도구이다.

이렇게 정리를 하고 보니, 내가 좀 이기적이었나? 하는 생각이 들었다.
나마저도 시간이 지나면 잊을 코드를 문서화도 해놓지 않고, 다른 동료 혹은 미래의 내가 잘 작업하기를 바랬던 것…….
이제부터라도 잘하자

How.(문서화하는 방법)

정확하게는, “README 파일 작성하는 법.”

README 파일의 목적은 그 프로젝트를 처음 보는 사람이 프로젝트를 이해하고 작동시킬 수 있도록 하는 것이다.

이를 위한 최소한의 정보가 작성되어있어야 한다.

  • What & Why
    • 프로젝트 제목
    • 프로젝트 설명
  • How
    • 작동 전, 준비 사항
    • 작동 방법

각 Section은 짧고, 명료하게, 꼭 필요한 내용만 작성한다. 그리고 다른 사람을 위한 작업임을 명심한다. (예시 1, 예시 3)
작성하는 법이 정해진 것은 아니지만, 강의에서 권장하는 구조는 아래와 같다. 

1
2
3
4
5
6
7
8
# 프로젝트 제목
프로젝트 설명 (with 프로젝트 Logo)

## 설치 방법 (Installation)
설치 방법 설명 (with 예시코드)

## 사용 방법 (Usage)
사용 방법 설명 (with 예시코드)

(오픈소스 프로젝트일 경우 아래 내용 추가)

1
2
3
4
5
## 기여 방법 (Contributing)
기여 방법 설명

## 라이센스 (License)
해당하는 License (choosealicense.com 참고)

(프로젝트의 규모가 커진다면, 아래 내용 추가)

1
2
3
## 버그들 (Known Bugs)
## FAQ (Frequently Asked Qustions)
## ToC (Table of Contents)

마치며

쉽고 당연한 내용이지만, 나에게는 짚고 넘어갈 필요가 있는 내용이었다.

목적에 대해서는 확실히 이해하였고, 방법은 계속해서 다듬어나갈 것 같다.

문서화. README부터 시작하자!