README.md 파일을 어떻게 쓰면 좋을까?

1. 들어가며

캡스톤 디자인을 진행하면서 개발한 내용을 문서로 작성하는 일이 너무 번거롭고 힘들었다. 

'개발할 시간도 부족한데 이걸 왜 하고 있어야 하지?', '여기에 쏟을 정성을 코드에 쏟으면 안 되는 건가?' 이런 생각을 하면서 교수님이 너무하다는 생각을 했다.

 

하지만 누군가와 내가 만든 프로젝트를 가지고 이야기를 해야 할 때, 팀원들과 프로젝트에 대해서 회의를 해야 할 때, 시간이 지나고 나서 자기소개서를 작성하면서 가장 도움이 되었던 것이 그때의 문서였다. 머리 속에서는 대충 어떤 것을 만들었는지 기억이 나지만, 막상 다른 사람에게 '이 프로젝트는 어떤 서비스이며, 어떤 기술을 사용해서, 이러한 기능이 있습니다.' 라고 딱 정리해서 말을 하기란 매우 어려운 일이라는걸 깨달았다.

 

뒤돌아 생각해보면 기획자로서, 디자이너로서, 선생님으로서의 활동을 회고할 때도 내가 작성한 문서를 보거나, 같이 작성한 문서를 참고했다. 또 다른 사람이 올린 프로그램이나 프로젝트를 사용할 때도 이에 대한 문서를 보고 사용할지 말지를 정하기도 한다. 글로 정리하는 것이 중요하다는 걸 알면서도 '어떻게 써야 좋은 문서'가 되는지 가이드라인이 명확히 없어서 계속 핑계를 대면서 미룬거 같다.

 

그래서 오늘은 많은 문서 중 github의 README 파일에 대해 '나만의 가이드라인'을 정해보고, 이대로 작성하는 습관을 길러보려고 한다:)

물론 이 글도 나의 방향성이 달라질 때마다 업데이트 할 예정이다.

 

1. 리드미 파일이란?

리드미 파일은 파일에 대한 정보를 포함하고 있으며, 일반적으로 컴퓨터 소프트웨어와 함께 배포된다.

문서는 txt, markdown 등 다양한 형식으로 저장을 할 수 있다. 하지만 이 포스팅에서 중점적으로 말하고자 하는 리드미 파일은 github에서 가장 많이 사용되는 마크다운 형식의 리드미 파일이다. 

 

더 많은 구성요소들이 있겠지만, 리드미 파일은 보통 다음과 같은 구성으로 되어있는 거 같다. 

 

(1) 프로젝트 구성 안내 -  기술 스택 등

(2) 프로젝트 설치하는 방법

(3) 프로젝트 사용법

(4) 프로젝트 기능 설명

(5) 저작권 및 사용권 정보

(6) 버그

(7) 프로그램 작성자 및 도움을 준 사람

(8) 버전 (업데이트 소식)

(9) FAQ

 

2. 리드미 파일을 잘 쓰는게 왜 중요할까?

물론 내 자신이 계속해서 프로젝트를 관리하는 목적으로 사용하는 것도 있지만, 나를 포함한 다른 사람에게 이 프로젝트에 대해서 설명하는 파일이다.

보는 사람들로 하여금 필요한 정보들만 빠르게 캐치할 수 있도록 간단 명료하게 작성하는 것이 중요하다.

 

취업을 준비하면서 github 주소를 써야하는 경우가 있다. 아무리 열심히 짜고 깔끔하게 작성한 코드라도, 관계자가 모든 지원자의 코드를 보는 건 불가능하지 않을까? 만든 프로젝트를 어필하기 위해서 자기소개서 또는 이력서를 잘 쓰는 것도 중요하지만, '어떤 기능을 가진 프로젝트를 어떻게 만들었습니다.'를 한눈에 파악할 수 있는 파일을 만드는 게 가장 효과적이라고 생각한다. 

 

3. 나는 앞으로 어떤 식으로 리드미 파일을 이용해야 할까?

목록마다 꼼꼼하게 리드미 파일을 참고하면서 만들자니, 주객전도가 될 것 같아서 걱정이 되고-

그렇다고 틀만 맞춰서 대충 만들자니, 마음속 유노윤호 열정맨이 용납하지 않을 거 같은데,,

 

이에 여러 블로그를 돌아다니다가, 우아한테크코스의 백엔드 과정을 주관하고 계신 박재성님의 '우아한테크코스 프리코스 후기'글을 보았다. 자세한 내용은 블로그를 아래 참고한 사이트에 적어두었으니 보면 좋을 거 같다.

 

가장 인상 깊었던 것은 '기능을 구현하기 전에 README.md 파일에 구현할 기능 목록을 정리해 추가한다.', 'git의 commit 단위는 앞 단계의 README.md 파일에 정리한 기능 목록 단위로 추가한다.'라는 미션의 요구사항 내용이다. 또 프리코스 피드백 pdf에서 '리드미 파일에 작성하는 기능 목록은 구현을 하면서 변경될 수 있으니, 완벽하게 정리해야한다는 부담을 가지기 보다는 계속해서 업데이트를 해야한다. 살아있는 문서를 만들기 위해 노력해라' 라는 말도 인상적이었다.

 

그동안 기능을 분리해서 커밋을 하려고 노력했지만, 생각보다 깔끔하지 않았다. 또 리드미 파일도 기능 정리보다는 내가 해야하는 일에 초점을 맞추어 todoList가 된 기분이었다. 앞으로 나에게 주어질 미션도 이와 비슷하지 않을까라는 생각이 들었고, 주어진 과제나 토이 프로젝트를 진행하면서 다음과 같은 방식을 사용하기로 했다. 그 중 (1)은 꼭 하고, 나머지 (2)부터는 할 수 있는 부분까지 하는걸 목표로 삼았다.

 

(1) 주어진 미션 또는 프로젝트의 기능
(2) 결과 화면
(3) 프로젝트를 만들면서 이슈사항 (블로그나 notion에 따로 정리해서 링크로 연결시키는 것도 좋을 거 같음)

 

위와 같은 내용적인 측면도 중요하지만-

가장 중요한건, 문서는 언제든지 수정될 수 있는 것이기 때문에 너무 리드미 파일을 작성하는 것에 큰 부담을 가지지 않는 것이다.

그렇다고 해서 너무 간단하거나 대충 적지도 말아야 한다.

---

참고한 사이트 : 

위키백과 검색어 '리드미' : ko.wikipedia.org/wiki/%EB%A6%AC%EB%93%9C%EB%AF%B8

리드미 - 위키백과, 우리 모두의 백과사전

우아한테크코스 프리코스 후기 : brunch.co.kr/@javajigi/8#comment

목적의식 있는 연습을 통한 효과적인 학습