[Markdown] 웹 개발자를 위한 README.md 작성법

서론

Markdown은 문서를 작성하는 방법 중 특히 개발자들에게 상당히 보편적인 방법이라고 할 수 있다.

'.md' 확장자로 작성되는 문서들이 바로 마크다운으로 작성된 문서라고 할 수 있는데,

이런 마크다운이 편리한 이유는 텍스트를 쉽게 편집할 수 있을 뿐 아니라,

(개인적으로는 마우스를 쓰지 않아도 글씨 크기 조정, 양식화 등 다양한 일을 할 수 있어서 좋아한다 :)

HTML 등 다양한 형식으로 변경할 수 있기 때문이다. 

 

아무쪼록 내가 이번 포스트를 쓰게 된 이유는,

내가 작성했던 Repository들의 README.md를 보며 개인적으로 마크다운에 대해서 잘 알고 있었다고 생각하지만

막상 내 프로젝트의 README.md가 적절한 설명을 가지고 있는지에 대한 고민을 하게 되었기 때문이다. 

 

보통 프로젝트를 하게 되면 README.md를 좀 등한시하게 되는 부분이 없지 않아 있다.

 

더 중요한건 개발 아닌가요? README는 그냥 설명서일 뿐인데..

 

라는 생각을 무심결에 하게 되기 때문이다.

주변 사람들 중 README.md를 꼼꼼하게 작성하는 사람도 드물게 본 것 같다.

 

오죽하면 이런 사이트도 있을까...

 

그렇지만 프로젝트가 길어질수록, 거대해질수록

README.md를 꾸준히 수정하고 업데이트하는 건 중요한 일이라고 생각한다.

나를 위해서, 함께 작업하는 동료를 위해서, 또한 오픈 소스로 내 코드를 볼 다른 사람들을 위해서

README.md를 꼼꼼히 작성해야 할 필요성이 있다.

(필자는 최근 매우 반성하고 있다.. 이전의 프로젝트들의 README.md를 리팩토링할 필요성을 느낀다..)

 

이처럼 중요한 README.md를 잘 작성하기 어려운 이유는 무엇일까?

결정적인 이유 중 한 가지는,

도대체 무엇을 써야 할지 생각이 잘 나지 않기 때문이라고 생각한다.

필자의 경우도 막상 쓰려다가 '음... 뭘 써야하지'하고 막막해지는 경우를 자주 겪었기 때문에

이번 기회를 통해 어떤 내용이 들어가야 할지 좀 고민해보기로 하였다. 

(참고로 필자는 웹 개발자이며 이에 치중할 수 밖에 없음을 미리 명시한다. 또한 보통 저장소로 Github을 사용하는 편임을 밝힌다.)

 

 

프로젝트에 대한 간략한 Description

우리가 어떤 프로젝트를 하고 있는지, 어떤 내용의 서비스를 위한 코드인지에 대해

밝히는 것이 제일 먼저라고 생각한다.

이 설명은 굳이 길지 않아도 된다고 생각하며, 오히려 간결하게 쓸수록 더 유용하다고 생각한다.

다만 너무 간결하지 않으며 우리 프로젝트의 가치를 잘 전달할 수 있는 직관적인 문구로 작성하는 것이 중요하다.

 

React Github의 Description 예시. 간략하면서도 알아보기 쉽다.

 

실행 방법(컴파일 방법, 환경 포함)

우리가 작성한 코드들을 어떻게 실행해야 할지에 대한 내용은 꼭! 꼭! 담겨 있어야 한다.

다만, 이 내용은 비교적 구체적으로 적어야 할 필요가 있다.

본인이 실행해 본 환경은 어떤 환경인지, 컴파일러로는 무엇을 사용했는지와 같이

프로그램에 의존성(Dependency)이 걸리는 내용들을 써줘야 한다.

(보통 OS, Compiler 정도를 쓰고 Multicore 환경에서 돌아가는 프로그램이라면 CPU, RAM 등도 써주는 것이 좋다.)

또한 언어의 버전도 적어줄 수 있다면 적어주는 것이 좋다.

 

nodemon Github의 설치 설명. 간략하면서도 잘 적혀 있다.

 

+ 브라우저 서포트

웹 개발자라면 다들 아는 부분이겠지만, 그래도 혹시 몰라 한 번 더 적어본다.

실제로 서비스를 하다 보면 '크로스 브라우저' 이슈를 겪는 경우가 상당히 많다.

특히 이 이슈는 IE 때문에 숱하게 겪어왔던 문제이기도 한데,

의외로 크롬에서는 잘 돌지만 사파리에서 문제가 생기는 경우도 있다.

또한 브라우저의 경우 버전마다 지원하는 형식이나 기능이 다를 수 있기 때문에 버전도 명시해주는 것이 좋다.

 

본인 Github에 작성했던 브라우저 서포트 예시

 

사실상 여기까지만 써도..

이미 꽤 훌륭한 지침서라고 할 수 있다.

나머지는 코드에 첨부된 주석을 통해 읽고 이해하는 과정이 더 필요하다고 할 수 있다. 

그렇지만, 추가하면 더 좋을 법한 것들을 세 가지 정도 적고자 한다.

 

본인이 모듈, 라이브러리 혹은 API 서버를 만들었다면,

사용방법에 대해 기재해주는 것이 좋다.

대부분 큰 오픈소스의 경우 Documentation을 따로 준비해두지만,

그것이 벅차다고 생각하면 간단한 사용 방법, 예제 정도는 준비해 주는 것이 모두에게 좋다. 

혹은 issue로 올려놓으면 착한 천사같은 Contributor가 도움을 줄 수도 있다.

 

React의 Example. 리액트는 참 이런걸 잘 해놨다.

 

Contributor를 위한 안내서

Contributing을 하는 방법은 거의 비슷하다고 할 수 있지만,

어떤 류의 Contributing을 원하는지 혹은 Contributing 규칙 같은 것을 적어둘 수도 있다. 

본인의 오픈 소스를 지속 발전하고 싶다면 이에 대해 본인이 원하는 바에 대해 적어두는 것도 좋다고 생각한다.

 

License

라이선스에 대해서는 생각보다 많은 사람들이 모르고, 생각보다 많은 사람들이 그냥 사용한다.

라이선스는 카피레프트, 즉 저작권에 기반하여 정보의 공유를 위한 것으로 

저작물의 수정 배포에 대한 권한이나 저작권에 대한 조항들이라고 생각하면 된다. 

보통 느슨한 MIT License를 많이 사용하며 BSD 라이선스도 많이 사용하는 것 같다.

기회가 된다면 각 라이선스에 대해서도 알아보는 것이 좋으며, 오픈소스 활동을 할 때 꼭 알아보도록 하자.

Github의 경우 이렇게 라이센스도 표시가 된다.

 

추가적으로..

개인적으로 Badge를 좋아한다. 

뱃지는 말 그대로 Repository에 현재 버전, 빌드 성공, 테스트 코드 비율, PR 받는지 여부 등등을 다는 것인데

간단하면서도 사람들이 중요한 내용을 빨리 볼 수 있어서 좋다.

기회가 되면 뱃지를 달아보는 것도 좋다.

귀여운 뱃지를 달 수도 있다!

 

* 마크 다운 문법 at Github

https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax

Basic writing and formatting syntax - GitHub Help