[Markdown] README.md 작성하는 방법

[Markdown] README.md 작성하는 방법

 

source : https://bulldogjob.com/readme/how-to-write-a-good-readme-for-your-github-project

 

요즘 Notion에 수업 들은 것을 집어넣고 있는데, markdown을 접하고 있었다. 

마침 또 내가 만들어 놓은 페이지들을 깃허브를 통해서 배포하고 싶었고, 이것도 프로젝트라면 프로젝트라 readme가 필요해졌다.

readme를 markdown으로 작성하는 방법을 알아보자.

 

1. README란?

 

프로젝트를 소개하는 문서이다.

관련된 링크, 개발을 위해 갖춰야 되는 실행환경, 사용 라이브러리, 가이드라인, 특정 코드 설명 등등을 쓴다.

이 프로젝트를 진행한 구성원이 아니라도 이것을 보고 수정, 보완을 할 때 도움이 될 수 있도록 도움이 되는 설명서와 같은 것이다.

 

 

2. Markdown 문법

 

'#'과 '>', '*', ''' ~~~ ''', 등을 활용하면 멋진 readme 문서를 만들 수 있다.

그렇지만 문법을 하나하나 다루기에는 마크다운은 많은 문법들을 가지고 있다.

아래의 깃허브 블로그에 아주 훌륭하신 분이 문법들을 정리해 두었다.

 

https://gist.github.com/ihoneymon/652be052a0727ad59601

마크다운(Markdown) 사용법

(감사합니다)

 

 

3. README 작성

 

이제 내용을 써보도록 하자. 다음과 같은 항목들이 작성되면 된다

1. Project명 (Header 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.프로젝트가 커질수록 도움이 되는 부분이다.

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


참고 블로그 : https://www.quantumdl.com/entry/Github-READMEmd-작성법

 

 

4. Markdown 문서 에디터

 

마크다운 문서를 작성할 때, 텍스트 편집기를 사용해도 되지만, 즉각즉각 어떻게 나오는지 알면서 하는 것이 더 편할 수 있다.

그럴 때 사용하는 것이 바로 마크다운 에디터.

 

https://stackedit.io/app#

StackEdit

이곳에서 마크다운 문서를 작성해 볼 수 있는데, 각 기호마다 구현되는 것들을 바로 오른쪽에서 확인 할 수 있다.

이런식으로 왼쪽에 마크다운 양식으로 작성한 글을 오른쪽에서 바로 확인하면서 작업을 할 수 있다.

 

 

 

자 그러면, 본격적으로 README.md를 작성을 해보러 가보겠습니다.

이만..