좋은 리드미에 대하여
좋은 프로젝트에는 좋은 리드미가 있다. 리드미까지 포함해서 하나의 프로젝트인 것이다.
리드미 파일을 신경쓰기 시작한 것은 얼마되지 않았다. 이전까지는 아예 작성하지 않거나 간단한 프로젝트 설명이나 적었을 뿐이다.
그러던 중, 프로젝트에 대한 포트폴리오를 작성해야 해서 그걸 리드미에 적었다. 최소 이 시점에서는 리드미 = 포트폴리오 적는 공간이라는 잘못된 이해가 있었던 것이다.
하지만 '뭔가 이건 아닌거 같다'라는 생각이 스멀스멀 올라와서 좋은 리드미를 작성하는 법을 검색하고, 또 읽어보니 내가 방향성을 잘못 잡았음을 알았다. 리드미에 이 프로젝트가 무엇인지가 아니라, 이 프로젝트를 어떻게 만들었는지만 쭉 늘어놓았던 것이다.
지금 내가 이해하기로는 포트폴리오는 어떻게 이 프로젝트를 만들었는지를 설명하는 '기술설명서'라면, 리드미는 왜 이 프로젝트를 만들었고 어떻게 사용하는지에 대한 '사용설명서'라는 개념이 잡혔다.
이하의 내용은 참고한 포스트의 내용을 간추린 것이다. 직접 해당 포스트를 보는 것이 이해에 더 큰 도움이 될 것이다.
주의점
리드미를 작성함에 있어 가장 주의해야 할 점은 리드미를 쓰는 방법은 한가지가 아니라는 것이다.
오히려 가장 좋지 않은 방법은 하나 있다. 리드미를 전혀 작성하지 않는 것이다.
프로젝트의 리드미는 프로젝트의 '무엇을, 왜, 어떻게'에 답해야 한다.
- 동기가 무엇인가?
- 왜 이 프로젝트를 기획했나?
- 이 프로젝트는 어떤 문제를 해결하나?
- 이 프로젝트를 통해 무엇을 배웠는가?
- 이 프로젝트의 특징은 무엇인가?
리드미에 들어가야 할 내용
1. 프로젝트 명
한 문장으로 전체 프로젝트를 설명하고, 프로젝트의 주 목표가 무엇인지 이해할 수 있게 도와준다.
2. 프로젝트 설명
- 어플리케이션이 무엇을 하는지
- 왜 그 기술을 사용했는지
- 당면했던 문제나 나중에 추가하고 싶은 기능
3. 목차(선택)
리드미가 너무 길다면 목차를 통해 쉽게 프로젝트를 살펴볼 수 있게 한다.
4. 프로젝트 설치 및 실행 방법
프로젝트 설치 방법과 필요한 경우 dependencies를 포함해 작성한다. 개발 환경을 세팅하고 실행할 수 있는 단계적인 설명을 제공해야 한다.
5. 프로젝트 사용 방법
이용할 수 있는 방법과 예시를 작성한다. 예시 스크린샷 등 시각자료를 사용할 수 있고, 프로젝트의 사용된 구조나 디자인 원칙을 추가 할 수 있다.
6. 팀원 및 참고자료
팀이나 조직 단위로 작업한 프로젝트라면 팀원을 기재하고 깃허브 프로필, SNS 링크를 연결해야 한다.
프로젝트를 설치하는데 도움을 줄 수 있는 튜토리얼이나 자료를 참고했다면 그런 링크도 같이 첨부하는 것이 좋다.
7. 라이센스
라이센스를 보고 다른 개발자들은 해당 프로젝트로 무엇을 할 수 있고 무엇을 할 수 없는지 알 수 있다.
가장 흔한 라이센스는 다른 사람들이 여러분의 코드를 수정할 수 있고 상업적인 용도로 사용할 수 있는 GPL 라이센스이다.
추가적인 부분
8. 뱃지
뱃지를 사용하면 다른 개발자들이 프로젝트에 대해 쉽게 할 수 있다.
9. 프로젝트에 기여하는 방법
오픈 소스 프로젝트를 작업하고 있는 경우라면 향후 충돌을 막기 위해서 오픈소스 프로젝트에 사용되는 라이센스가 올바른 것인지 확인하는 것이 중요하다.
기여 가이드라인을 추가하면 큰 도움이 된다.
10. 테스트
테스트를 위해 예제 코드와 실행 방식을 작성한다.
참조
