오픈소스 만들어 Github에 올릴 때 하면 좋은 체크리스트 .. (2)

Github 블로그 글을 보며 정리한 글에 이어서 이번에는 README와 릴리즈 노트 관련 글을 읽고 정리했다.

https://dol9.tistory.com/338

오픈소스 만들어 Github에 올릴 때 하면 좋은 체크리스트 .. (1)

 

 

원래 아는 걸 실행하는 게 어렵다.

그래서 실행 할 때는 아무 생각 없이 할 수 있도록 준비하는 게 좋은데

단순하면서 꽤나 효과적이라고 생각하는게 금방 완료 가능한 할 일들을 체크리스트로 만들어 하나씩 완성해 나가는 것이다.

 

이 글은 체크리스트를 만들기 위해 정리가 목적이다.

---

https://www.daytona.io/dotfiles/how-to-write-4000-stars-github-readme-for-your-project

How to Write A 4000 Stars GitHub README for Your Project

 

프로젝트에서 README는 가장 중요하다.

처음 방문한 사용자가 스타를 누를지, 사용자가 될지, 기여자가 될 지 아니면 브라우저 탭을 닫을지 결정하는데 큰 영향을 끼친다.

 

HEADING

 

1. 로고 만들기

간과하기 쉬운데 첫줄에 로고가 있으면 깊은 인상을 준다.

 

2. 신뢰를 줄 수 있는 배지

프로젝트의 테스트 커버리지나 활성화 등 사용자에게 프로젝트의 건강함을 어필할 수 있다.

 

3. 프로젝트를 잘 표현하는 캐치프레이즈

프로젝트를 잘 표현하는 한 줄로 시작하고 다음 줄에 추가 설명을 진행하면 좋다.

사람들의 관심을 끄는데 매우 중요하다.

 

4. 이미지나 애니메이션 같은 시각화

글만 있는것보다 시각화 자료가 함께 있다면 더욱 좋다.

 

5. 기능 소개

지금까지 사람들의 관심을 끌었으니 프로젝트에서 매력적인 기능을 나열한다.

다른 프로젝트와 차별되는 고유한 가치를 강조해서 사용자가 관심을 넘어 호기심을 갖도록 한다.

 

6. QuickStart

최소한의 명령어로 프로젝트를 활용할수 있는 방법을 보여준다.

 

 

BODY

 

1. Why

여기까지 읽은 사용자의 관점으로 프로젝트에 참여해야 하는 이유를 명확하게 설명한다.

그들의 필요와 문제를 해결해줌으로써 관계 구축에 도움이 된다.

 

2. 배경설명

대부분의 프로젝트가 없지만 배경설명 적는 걸 추천한다.

당신이 프로젝트를 시작하게된 동기와 여정들을 공유하면, 독자가 더욱 공감 가고 기억에 남게 해 준다.

 

3. Getting Started

QuickStart의 확장버전이다.

프로젝트의 기능들을 종합적으로 설명을 해준다.

 

4. 간결하게 유지

불필요하게 README 파일이 길어지면 사용자는 프로젝트가 복잡하다고 느낄 수 있으므로 간결하게 유지한다.

 

 

프로젝트의 건강함(??)

사람들의 관심도 중요하지만 오픈소스가 지속하는 데는 프로젝트의 건강함에 달려있다.

 

1. Contributing

잘 작성된 기여 가이드는 컨드리뷰터들이 모범사례를 따라 유용한 문제를 작성할 수 있고,

표준화된 P/R을 제출할 수 있어 관리자가 프로젝트 관리를 쉽게 해 준다.

 

2. 라이선스

프로젝트의 라이선스 명확히 명시하여 지적 재산권과 권리 모두를 보호한다.

 

3. 행동강령

프로젝트가 커뮤니티와 어떻게 소통하고 사용할 것인지를 정의하고 컨드리뷰터들의 기대치를 설정한다.

 

4. 소통하는 채널 만들기

사용자가 도움을 요청하거나 문제 리포트, 또는 피드백을 제공할 공간을 명확하게 명시한다.

 

 

정리

앞에서 소개한 모든 항목들이 프로젝트에 가치를 더하는지 확인을 한다.

파일이 커지면 세부항목을 별도의 문서 폴더의 README 파일을 만들어 참조하는 것도 방법이다.

링크가 깨지거나 빈 README가 있는지 확인하고 깔끔하게 유지시킨다.