readme란 프로젝트에 대한 간단한 설명을 담고 있는 문서이다. 일반적으로 git에서 특정 레포지토리에 들어가면 가장 먼저 보이는 main page가 바로 readme이다. 이런 readme 파일은 일반적으로 markdown 문법으로 작성된다.(확장자는 md) 쉽게 말해 readme를 작성한다는 것은 구현한 프로젝트를 문서화하는 작업이다.
그렇다면 readme 파일은 도대체 왜 작성해야 할까?
위와 같은 이유로 readme를 작성한다. 귀찮지만 앞으로는 조금 더 신경써서 작성해야겠다.
캡스톤 디자인을 진행하면서 개발한 내용을 문서로 작성하는 일이 너무 번거롭고 힘들었다.
'개발할 시간도 부족한데 이걸 왜 하고 있어야 하지?', '여기에 쏟을 정성을 코드에 쏟으면 안 되는 건가?' 이런 생각을 하면서 교수님이 너무하다는 생각을 했다.
하지만 누군가와 내가 만든 프로젝트를 가지고 이야기를 해야 할 때, 팀원들과 프로젝트에 대해서 회의를 해야 할 때, 시간이 지나고 나서 자기소개서를 작성하면서 가장 도움이 되었던 것이 그때의 문서였다. 머리 속에서는 대충 어떤 것을 만들었는지 기억이 나지만, 막상 다른 사람에게 '이 프로젝트는 어떤 서비스이며, 어떤 기술을 사용해서, 이러한 기능이 있습니다.' 라고 딱 정리해서 말을 하기란 매우 어려운 일이라는걸 깨달았다.
뒤돌아 생각해보면 무슨 활동을 하더라도 내가 작성한 문서를 보거나, 같이 작성한 문서를 참고했다. 또 다른 사람이 올린 프로그램이나 프로젝트를 사용할 때도 이에 대한 문서를 보고 사용할지 말지를 정하기도 한다. 글로 정리하는 것이 중요하다는 걸 알면서도 '어떻게 써야 좋은 문서'가 되는지 가이드라인이 명확히 없어서 계속 핑계를 대면서 미룬거 같다.
그래서 오늘은 많은 문서 중 github의 README 파일에 대해 '나만의 가이드라인'을 정해보고, 이대로 작성하는 습관을 길러보려고 한다:)
물론 이 글도 나의 방향성이 달라질 때마다 업데이트 할 예정이다.
리드미 파일은 파일에 대한 정보를 포함하고 있으며, 일반적으로 컴퓨터 소프트웨어와 함께 배포된다.
문서는 txt, markdown 등 다양한 형식으로 저장을 할 수 있다. 하지만 이 포스팅에서 중점적으로 말하고자 하는 리드미 파일은 github에서 가장 많이 사용되는 마크다운 형식의 리드미 파일이다.