[git] README 작성법

서론

README는 프로젝트에서 가장 처음 보이는 페이지이며, 어떻게 쓰일 수 있는지에 대한 설명과 프로젝트를 돋보이게 해주는 수단이다. 생각해보라, 프로젝트에서 만든 어플리케이션 화면과 함께 꾸며진 리드미를 봤을 때, 프로젝트가 근사할거라는 기대감이 드는 경험 말이다.

 

 

본론

1. 공식화된 작성법이 있나?

No, 공식화나 권고된 작성 스타일은 딱히 보이지는 않는 것 같다.

오픈소스가이드, 깃허브, FreeCodeCamp 등을 조사를 해봤을 때, 수학공식처럼 명확하게 작성가이드 라인을 찾을 수 없었다. 이 글들을 읽어보았을 때 프로젝트 성격에 따라서 넣지 않아도 될 구성들이 있었다.

시야를 넓혀서 microsoft, toss, naver, naver map, kakao 등의 대기업의 레포지토리를 보면서, 수많은 사람들이 힘을 합쳐서 만든 리드미를 어떻게 작성했는지를 분석해보았다. 당황스러웠던 것은 같은 회사는 같은 문화나 스타일을 가질텐데, 한 회사의 레포지토리마다 리드미 작성 스타일이 다른 것이 있다는 것을 발견했다. 그래서 리드미는 정형화된 작성법이 존재하지 않는다는 결론을 내렸다.

 

2. 작성 스타일 탐색

toss는 리드미의 내용이 짧고 단순한만큼 빠른 시간내에 파악하기 용이했다. 아니, 사실 그럴수밖에 없었다, 우리는 글을 읽는 것을 대체적으로 싫어하며, 장황한 글보다 짧은 글일수록 이해하기 쉽다. 그래서 toss의 리드미는 글을 읽는데 부담이 없이 프로젝트가 무엇인지를 알기 쉬웠다.

나머지 microsoft, naver 등은 내용은 toss보다 길지만 내용이 디테일해서, 프로젝트를 사용하기 위해 준비해야하는 사항이나 오픈소스를 사용함으로써 얻어지는 기대효과, 오픈소스 기여방법 등 프로젝트에 대한 전반적인 정보를 얻기 용이했다. 

 

결론

'간략하게 설명하고 넘어가는 사람' vs '상황을 묘사하며 어떤 감정을 느꼈는지를 이야기를 계속 나누는 사람' 등 사람마다 표현방식이 다르듯이, 리드미의 작성법도 정해진 규칙은 없다. 의도에 따라 다르게 쓰면 된다. 만약 한눈에 알아보기 쉽게 하고 싶다면 toss처럼 최소한의 필수 내용만 적을 수 있으며, 읽는이 혼자서 별다른 노력을 기울이지 않고도 프로젝트를 사용 및 참여하게 하고 싶으면 microsoft, naver 등의 스타일대로 작성하면 된다.

다만 정해진 규칙 한가지는 프로젝트명과 함께 프로젝트의 설명/Description에 프로젝트의 역할, 프로젝트의 특징을 적어주어야한다. 만약 프로젝트의 특징이 너무 많으면, '특징' 세션이나 페이지를 만들어서 나열하는 것도 좋은 방법이다.

ps. 이 글을 쓰게 된 계기

문서를 작성하는 것은 어려운 일이다.

내가 이 글을 작성하게 된 계기는 '리드미는 빌드하는 방법만 적는거야!'라는 상사의 말이 타당하지 않다고 생각했다. 나름 열심히 노력해서 썼는데, 굳이 사람을 긁어내리면서 욕을 들었다. 그 상사가 수십년 동안 해왔던 것이 일반적인 것은 아닌데, '이게 일반적이다'라는 강요에 가스라이팅읍읍 굴복하고 싶지 않았다. 그래서 공부를 통해서 나 자신을 발전시키고자 글을 작성을 결심했다.

작성한 리드미에는 프로젝트 설명, 프로젝트의 기능들에 대한 설명과 사용법, 운영체제 제약사항 등의 내용 등 필요한 내용들을 적었다. 그리고 다른 팀의 상사분이자 CTO에게 비밀리에 피드백을 부탁드렸을 때, 중복되는 내용에 대해 조금만 다듬으면 좋은 내용이 될거라는 말을 들었다. 그리고 매번 시험 성적서 발급을 위해 출장을 가기 위해 문서작성을 했던 경험을 비춰보면, 이.쁘.게 작성해야 현재 개발에 대해 필요한 내용(간략한 api 사용법, 라이브러리 호출법 등)을 리드미에 반영할 수 있을거같다.

열심히 노력했지만 제 3자가 봤을때는 중복되는 내용도 있을테고, 필요한 내용만 있다고 하더라도 이미지나 테이블 등이 하나 없는 글처럼 전달이 쉽지 않다. 그래도 이번 계기를 통해서 내 주관적인 생각이라는 것을 가지는 계기가 되었다.