좋은 README.md 파일 만드는 방법

 

[개인 공부용 정리]

 

 

README 파일이란?

사용자가 레파지토리를 볼 때 가장 처음 보게 되는 것

사용자에게 프로젝트의 내용, 사용된 언어, 약관, 프로젝트가 수행할 수 있는 작업 등에 대한 개요를 제공하고 실행 중인 애플리케이션의 스크린샷을 보여준다.

 

 

 

README 파일이 중요한 이유

리쿠르터(채용 담당자)들이 이 README 파일을 보면서 내 프로젝트에 대해 알게 되기 때문에 프로젝트의 README에 프로젝트의 내용, 목적, 구현 방법에 대해 기록해놓는 것이 중요하다. 

 

README 파일에는 가장 중요한 정보를 포함시키고, 프로젝트와 사용된 기술 스택에 대한 명확한 설명을 제공하는 것이 중요하다.

또한, 다른 파일을 찾아보는 불필요한 서칭을 피하기 위해 README 파일에는 링크와 추가적인 정보를 제공하는 것이 좋다.

그렇지 않으면 리쿠르터(채용 담당자)가 내 프로젝트에 관심을 잃고 넘어갈 수 있다.

 

프로젝트에 대한 문서를 잘 작성하는 것은 매우 중요하다.

리쿠르터는 README 파일을 통해 프로젝트에 대한 정보 뿐만 아니라 내 문서 작업 능력과 디테일도 살펴볼 수 있다.

 

 

 

README 파일에 무엇을 작성해야 하는 지

아래 질문들을 고려하면 효율적을 작성할 수 있다.

• 무엇에 대한 프로젝트인가?
• 프로젝트 개발 이유가 무엇인가? (동기)
• 프로젝트는 무슨 문제를 해결하는가?
• 프로젝트를 통해 무엇을 배웠는가?
• 프로젝트에서 내세울 만한 것이 무엇인가?

 

 

설명

프로젝트의 목적과 설명은 포트폴리오를 보는 사람이 프로젝트 정보를 한 눈에 읽고 이해할 수 있도록 작성해야 한다.

 

 

 

기술 스택

프로젝트에서 사용한 프로그래밍 언어, 라이브러리, 프레임워크들을 포함한 기술 스택을 작성해야 한다.

만약 외부 공공 API를 사용하는 프론트엔드 애플리케이션이 있다면 언급하는 것이 좋다.

 

 

 

디자인

프로젝트와 관련한  UI의 예시를 작성한다.

프로젝트에 UI가 있다면 UI의 GIF, 비디오, 이미지 등을 삽입할 수 있다.

 

만약 프로젝트가 터미널에서 구동된다면, 작동 방식을 GIF 형식으로 보여줄 수 있다.

이러한 자료들을 통해 프로젝트가  어플리케이션과 어떻게 상호작용 하고 프로젝트 실행 시 어떤 것을 볼 수 있는 지에 대해 제공한다.

 

 

 

기능

프로젝트에 기능이 많다면, 따로 '기능' 섹션을 추가하고 그곳에 특징을 작성한다.

 

 

 

프로젝트 실행 방법

프로젝트 설치 방법, 구동 방법, 실행 방법에 대한 지침을 작성한다.

프로젝트를 실행해보길 원하는 사람이 제작자의 도움 없이도 이해할 수 있도록 프로젝트의 README에는 사용자에게 필요한 모든 정보가 있어야 한다.

 

만약 실행 방법이 간단하다면 그냥 README 파일에 포함해도 된다.

만약 지침이 길다면 프로젝트 내 또 다른 파일을 참조할 수 있다. 

 

또한 프로젝트를 호스팅해야 한다. 

예를 들어 Netlify를 사용하여 배포하면 사용자가 바로 앱을 열어서 작동 방식을 확인할 수 있다.

 

 

 

 

README 파일 작성 스타일

README.md 파일의 .md 확장자는 텍스트 서식 지정을 위한 간단한 문법을 가진 경량 마크업 언어인 Markdown을 나타낸다.

Markdown은 GitHub에서 전달력 있는 README 파일을  만들 수 있는 매우 간단한 언어이다.

 

일반적으로는 Markdown 언어로 README 파일을 작성한다.

# Heading 1
## Heading 2
### Heading 3

Emphasis, aka italics, with *asterisks* or _underscores_.

Strong emphasis, aka bold, with **asterisks** or __underscores__.

Combined emphasis with **asterisks and _underscores_**.
1. First ordered list item
2. Another item
⋅⋅* Unordered sub-list. 
1. Actual numbers don't matter, just that it's a number
⋅⋅1. Ordered sub-list
4. And another item.

[I'm an inline-style link](https://www.google.com)
[I'm an inline-style link with title](https://www.google.com "Google's Homepage")
![descriptive alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

 

 

 

 

README 파일 예시

GitHub - YuriDevAT/sos-animals: This app will help abandoned animals get help from Animal welfare organizations all over the wor

 

GitHub - YuriDevAT/nikki-my-diary: Nikki is an online journal, which helps the user improve their Japanese Skills by writing dow

 

 

---

출처

 

How to create a good README.md file