README를 쓰는 것과 안 쓰는 것의 차이

README를 쓰는 이유?

깃허브에서 레포지토리를 생성할 때 Readme.md 파일을 생성할지 말지 묻는 경우가 있다.

예전엔 그냥 뭔가 ‘있어 보여서’ 만들었는데, 스타 몇만개씩 찍힌 오픈소스 레포들에 기깔나게 꾸며진 리드미 파일을 보고 그런 느낌을 받았기 때문이었다.

근데 이제는 생존의 도구로 리드미를 꾸미기 시작했는데…

프로젝트 설명

깃허브는 깃 저장소 호스팅을 지원하는 웹 서비스다. 프로젝트를 하게 되면 필히 버전관리를 하게 되는데, 버전관리를 위해 사용하는 깃을 GUI를 통해 보다 직관적이게 표현하는 호스팅 서비스 중 가장 유명한 것이 깃허브인 것. 그래서 많은 개발자들이 깃허브를 본인의 포트폴리오로 대신 표현하고 있다.

포트폴리오에는 단순히 내가 한 것의 결과만 첨부되어있지 않다. 어떤 Role을 맡았고, 어느정도의 기여도를 가지며, 나의 수많은 삽질의 흔적을 있어보이게 쓰는 것이 포트폴리오의 생명인 것 같은데…

그 맥락에서 봤을 때, 프로젝트 포트폴리오 그 자체가 될 수 있는 깃허브 레포지토리를 설명할 수 있는 가장 좋은 창구가 리드미 파일이다.

마크다운 형식

마치 사무 업무를 보는 사람들의 기본 기술 스택이 MS Word, 한컴의 한글 등인 것과 같이, 개발자의 기본 문서 기술 스택은 마크다운이다.

깃허브 뿐만 아니라 개발자가 사용하는 대부분의 프로그램 및 서비스에서 마크다운 형식을 주로 사용하고 있다. 나는 현재 깃허브 블로그를 포스팅하고 있는데 이 글도 마크다운 형식으로 만들어진 파일이다. VSCode를 사용해 마크다운 형식으로 글을 쓰고, 깃으로 푸시하면 깃허브 블로그에 업로드된다.

앞서 말한 깃허브, 블로그 뿐만 아니라 생활(?)에서 많이 쓰는 노션, 디스코드, 슬랙 등 다양한 커뮤니케이션 도구에서도 마크다운 형식을 알면 상당히 가독성 있고 좋은 메시지를 전달할 수 있다.

잘 꾸며진 리드미를 통해 간접적으로 나의 마크다운 형식의 이해도, 활용도를 보여줄 수 있다.

미리미리 해놓자

프로젝트가 끝나면 배포하고 끝~ 하는 경우가 많은데, 미리미리 문서화를 잘 해두고 알찬 내용으로 한껏 채워 리드미를 꾸미자.

똑같은 수준으로 작업을 했는데 한 사람은 휑하니 Readme.md로 끝나있고 다른 사람은 프로젝트 내용에서부터 스크린샷, 사용법, 샘플 코드까지 쭉 다 있다면 후자 쪽에 더 좋은 점수를 주게 되지 않을까?