리드미는 왜 작성해야하나 🙄
부트캠프에서 진행했던 프로젝트에서 깃 관리자를 맡았기 때문에 버전 관리 뿐만 아니라 리드미 또한 작성하게 되었다.
리드미에는 어떤 내용이 들어가야 하는지 궁금해, 검색을 통해 찾아보았다.
참고글에 따르면, README란..
내가 작업한 프로젝트를 세상에 공개할 때 구체적인 설명을 제공하는 가이드 역할을 해주는 것이라고 한다.
프로젝트를 문서화시키는 리드미를 왜 써야하는가에 대한 이야기도 나오는데 다음과 같은 이유이다.
- 프로젝트에서 가장 먼저 보이는 부분이기 때문에
- 프로젝트를 돋보이게 해주는 요소이기 때문에
- 프로젝트가 무엇을 전달하고 싶은지에 대해 집중할 수 있게 해주기 때문에
- 리드미를 작성하면 글쓰기 능력이 향상되기 때문에
참고글에 좋은 명언도 함께 나온다.
훌륭한 작가는 자신의 생각뿐만 아니라 친구들의 생각까지 마음에 품고 있다.
-프리드리히 니체(Friedrich Nietzsche)
프로젝트의 결과물이 아무리 뛰어나더라도 대부분의 개발자들은 잘 쓰여진 리드미가 없다면, 그 프로젝트에 관심을 보이지 않을 것이다.
그래서 이 프로젝트는 어떤 프로젝트인지, 어떤 내용을 포함하고 있는지, 이용하거나 기여하려면 어떻게 해야하는지 작성할 필요가 있다.
리드미는 어떻게 작성해야하나 🤔
자, 그럼 이제 리드미를 어떻게 작성해야하는 것이 좋은지에 대해 알아보자.
하나의 알고리즘 문제를 푸는 것에 하나의 정답이라는 게 없듯이,
리드미를 작성하는데에 있어서 정답이란 없다.
하지만, 리드미를 작성하지 않는 것은 위에 언급한 이유를 보았을 때 오답이라 단언할 수 있다.
좋은 리드미를 작성하기 위해서는 당연하지만 반드시 지켜져야 할 것들이 있는데, 리드미를 작성할 때 프로젝트의 무엇을, 왜, 어떻게에 대해서 답해야한다.
쉽게 생각나지 않는다면, 다음과 같은 질문에 답하는 걸로 시작해보자.
- 이 프로젝트를 기획한 이유가 뭔가요?
- 이 프로젝트는 어떤 문제를 해결하나요?
- 이 프로젝트를 통해 무엇을 배우셨나요?
- 이 프로젝트의 특징은 무엇인가요?
리드미에는 어떤 내용이 들어가야하나 👀
프로젝트 이름
리드미에는 가장 첫 번째로 프로젝트 이름이 들어간다. 프로젝트 이름으로 전체적인 프로젝트의 느낌을 전달하고 프로젝트의 주 목표를 알 수 있게 해준다.
프로젝트 설명
프로젝트에서 매우 중요한 부분을 차지한다.
프로젝트 설명은 좋은 프로젝트와 그렇지 못한 프로젝트를 구분 짓는다. 잘 작성된 설명은 리드미를 읽는 사람들에게 여러가지를 전달해준다. 프로젝트를 이용해보지 않고도 프로젝트 전반을 이해할 수 있게 만들어주기도 한다.
- 이 프로젝트가 무엇을 하는지
- 이 프로젝트에 어떤 기술들이 왜 사용되었는지
- 이 프로젝트를 진행하면서 어떤 문제에 당면했는지
- 이 프로젝트에 추후 추가하고 싶은 기능이 어떤 것인지
프로젝트 시연을 gif 또는 스크린샷을 이용한 시각 자료로 첨부하는 것도 좋은 방법 중에 하나이다.
프로젝트에 어떤 기술이 사용되었는지 글로 나열해도 되지만, 아이콘을 사용하면 훨씬 더 직관적이고 간결하게 설명할 수 있다. 나는 skillicons를 주로 사용한다.
또한, 뱃지를 사용하면 포크, 기여자, 오픈된 이슈, 버전 등 프로젝트에 대한 통계를 다른 개발자들이 쉽게 파악할 수 있다. 뱃지는 여기에서 만들어보자. 뱃지는 한 번 달아두면 자동으로 업데이트되어 수정할 필요가 없다. 다음 사진은 shields.io에서 캡쳐한 뱃지 예시이다.
목차 기능을 사용해보자!
만약, 프로젝트 설명이 너무 길어진다면, 목차 기능을 사용해보자.
읽는 사람들이 쉽게 프로젝트를 쉽게 살펴볼 수 있도록 도와줄 것이다.
나는 이 글의 도움을 얻어 작성했다.
프로젝트 설치 및 실행 방법
프로젝트 사용자 또는 기여자가 프로젝트를 이용할 수 있도록 방법과 예시를 작성하자.
설치 및 실행 과정에서 발생할 수 있는 예상 문제에 대해 항상 참고할 수 있는 것을 마련하면 더 좋다.
예를 들면, 프로젝트의 수월한 이용을 위해 계정을 적어두는 방법이 있다.
팀원 및 참고 자료
팀 단위로 작업한 프로젝트라면 팀원들을 같이 기재하자. 팀원들의 Github 프로필과 SNS 링크도 연결하는 것이 좋다.
프로젝트를 진행하며 참고한 자료들이 있다면 여기에 모두 링크로 첨부하자.
이렇게 함으로써 팀원들에게 감사를 표할 수 있으며, 프로젝트의 첫 번째 사본을 제공해줄 수 있다.
라이센스
대부분의 프로젝트에서 라이센스는 마지막으로 고려되는 부분이다. 라이센스를 보면 다른 사람들이 이 프로젝트로 무엇을 할 수 있고, 무엇을 할 수 없는지를 알 수 있다.
라이센스는 프로젝트의 종류에 따라 달라지게 된다. 어떤 라이센스를 고르는지에 따라 프로젝트의 기여 또한 달라지게 된다.
마치며 😃
리드미를 작성할 시간이 없다면 자동으로 생성해주는 도구도 있다.
하지만, 자동화하기 전에 먼저 스스로 만들어보는 것이 글쓰기 능력 향샹, 프로젝트 집중도 면에서 더 좋을 것 같다.
