낙서장이자 오답 노트이자 컨닝 페이퍼
아 나도 리드미 잘 쓰고싶다~ 본문
리드미 공포증
항상 리드미라는 글자를 볼 때마다 알게 모르게 거부감이 있다. 왜냐하면 리드미를 작성하려고 키보드 위에 손을 올려놓으면 도대체 어떻게 작성해야 할지 감이 안 잡혀서 시간만 축냈기 때문이다.
언제는 팀플을 하다가 나한테 리드미를 작성해 달라고 부탁을 받았던 적이 있었는데 거절할 수 없어서 작성하긴 했지만 그때 속으로 큰일 났다 싶었다.
하지만 이제 리드미에 두려워하는 것도 질리고 리드미 잘 쓰는 좀 있어 보이는 개발자가 돼보고자 리드미를 잘 쓰는 법에 대해서 공부해 봤다!
리드미란?
한마디로 사용자가 작업한 프로젝트에 대한 설명, 설치, 사용 방법, 라이센스 등을 제공하는 가이드다.
리드미를 써야 하는 이유
1. 차별성
훌륭한 리드미는 프로젝트를 특별하게 만들어 준다!
부실한 리드미는 프로젝트가 아무리 훌륭해도 입구컷이다!
2. 미래의 나를 위해
좋은 리드미는 미래에 프로젝트를 다시 볼 내가 이해하기 쉽게 해준다!
부실한 리드미는 멍청해진 나를 계속 멍청하게 내버려 둔다!
3. 다른 개발자들을 위해
좋은 리드미는 다른 개발자들이 프로젝트를 이해하는데 도움을 줌으로써 협업을 촉진시킨다!
안 좋은 리드미는 다른 개발자들이 프로젝트를 이해하기 어렵고, 이해하지 못할 수도 있으며, 심지어는 이해하려고 노력하지 않을 수도 있다!
리드미에 들어가면 좋을 내용
1. 프로젝트 제목
전체 프로젝트를 한 문장으로 설명하고 주요 목표를 이해하도록 돕는다.
2. 목차
우리 소중한 독자들이 다른 섹션으로 이동하기 쉽도록 목차를 추가해 주면 좋지 않을까?
3. 프로젝트 설명
프로젝트가 구체적으로 무엇을 할 수 있는지, 목표가 무엇인지, 어떤 문제를 해결하는지 설명한다.
설명을 잘하면 초장부터 우리의 프로젝트를 머리에 똑똑히 심어줄 수 있다!
아래와 같은 내용이 들어갈 수 있다.
- 프로젝트가 수행하는 기능
- 프로젝트를 만든 이유와 목표
- 다른 프로젝트와의 차별화 요소
- 직면한 몇 가지 문제와 향후 구현하고자 하는 기능
4. 기술 스택
기술 스택들을 적어준다! (해당 기술을 선택한 이유들도 적어주면 좋을 것 같다)
아래와 같이 기술 스택 배지를 사용해 주면 리드미를 이쁘게 꾸밀 수 있다!
5. 시작하기
시작하기 단계는 개발 환경에 대한 정보를 알려주는 요구사항 단계와 실행 방법을 제공하는 설치 및 실행 단계로 나눌 수 있다!
(1) 요구 사항
프로젝트를 설치하기 전에 필요한 요구사항을 적어준다
- Node.js version
- npm version
(2) 설치 및 실행
설치하는 단계를 적어준다. 이때 환경변수 설정 같은 내용들도 적어주도록 하자!
git clone http://url-to-my-repo
npm install
npm start
6. 프로젝트 사용 방법
프로젝트 사용 방법과 예제를 제공하자!
스크린샷, 코드 블록, 비디오 같은 요소들을 이용하여 예제를 제공하면 독자들이 읽기 더 쉽다.
(웹 서비스 같은 경우에 프론트는 화면 구성, 백엔드는 API 명세서 링크를 걸어두면 좋겠다.)
7. 팀원
프로젝트에 참여한 팀원들을 적어두자! GitHub 프로필에 대한 링크도 포함해야 된다!
8. 외부 리소스
다른 사람의 코드를 참조한 경우 해당 정보를 추가해야 한다!
영감을 얻은 방식, 변경 사항, 개발된 기능을 작성할 수 있다.
9. 라이센스
소프트웨어 사용의 한계를 이해하는 데 도움이 되므로 라이센스를 설정하는 것이 중요하다.
중요하게 생각 안 할 수도 있지만 오픈소스의 라이센스에 따라서 회사의 소스를 공개해야 할 수도 있다!
대표적인 라이센스로는 MIT와 GPL이 있다
- MIT는 가장 단순한 라이센스로써 이 코드로 원하는 것은 무엇이든 할 수 있다!
- GPL은 코드의 기여 또는 사용자 정의를 공개적으로 발표하고 동일한 GPL 라이선스로 배포하도록 강제하므로 MIT보다 더 제한적인 라이센스다!
10. 기여 방법
이 부분은 오픈 소스 프로젝트를 개발하는 경우에 중요하다.
오픈 소스 프로젝트라면 프로젝트에 기여할 수 있는 방법을 추가해 주자!
아래와 내용과 같은 부분들이 있을 수 있겠다
11. 테스트
테스트를 작성하고 예제와 실행 방법을 제공하자!
그러면 프로젝트가 문제없이 잘 돌아갈 것이라는 확신을 줄 수 있다!!
참조
https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/
How to Write a Good README File for Your GitHub Project
When I was first introduced to GitHub, I had no idea what it was or what it could do. Between you and me, I created the account because I was told every developer should have one where they push their code. For the longest time as a beginner I did
www.freecodecamp.org
https://meakaakka.medium.com/a-beginners-guide-to-writing-a-kickass-readme-7ac01da88ab3
A Beginners Guide to writing a Kickass README ✍
Hey beginners,
meakaakka.medium.com
Github 프로젝트 README 쓰는 법
Github 프로젝트 README 쓰는 법에 대한 나름대로의 팁을 써보려고 한다
velog.io
'git & github' 카테고리의 다른 글
| Git을 공부해보자: GitHub 사용하기 (0) | 2023.11.15 |
|---|---|
| Git을 공부해보자: Git으로 차원 넘나들기 (0) | 2023.11.15 |
| Git을 공부해보자: Git으로 시간 여행하기 (0) | 2023.11.14 |
| Git을 공부해보자: Git 시작하기 (0) | 2023.11.14 |
| 커밋 메세지 어떻게 써야할까? (0) | 2023.07.28 |