오픈소스 프로젝트 최대의 적? "엉터리 문서"

깃허브 조사 결과…응답자 93% "불충분, 혼란스런 문서"

컴퓨팅입력 :2017/06/05 13:43    수정: 2017/06/05 13:44

오픈소스 프로젝트에 기여하거나, 활용하려할 때 맞닥뜨리는 가장 큰 난관은 뭘까? 인기 소스코드 저장소 깃허브가 실시한 ‘2017 오픈소스 서베이(☞링크)’ 조사 결과 '부실한 문서화’인 것으로 나타났다.

2일(현지시간) 깃허브는 커뮤니티 멤버 약 5천500명과 외부 개발자 500여 명을 대상으로 실시한 설문조사 결과를 발표했다.

설문 문항 중 “오픈소스에서 맞닥뜨리는 문제가 무엇인가”를 묻는 질문에 약 93%의 응답자가 “불충분하거나 혼란스러운 문서화’로 어려움을 겪고 있다고 답해 관심을 끌었다.

문서화는 해당 프로젝트에 대한 사용 방법은 물론, 기여하는 방법, 사용 및 기여 조건, 커뮤니티 행동 기준 등에 대한 지침을 제공한다. 따라서, 문서화 잘 돼 있어야 프로젝트를 활용하고, 기여하는 사람이 늘어날 수 있다.

대다수의 오픈소스 커뮤니티 참여자들이 부실한 문서화로 여러움을 겪고 있는 반면, 컨트리뷰터(오늪소스 기여자) 중 60%는 문서화에 기여해 본 경험이 전무하거나 거의 없다고 답해 보다 적극적인 문서화 기여가 필요한 것으로 나타났다.

깃허브 측은 "문서화 개선을 돕는 일은 오픈소스에 다시 개여할 수 있는 아주 중요한 방법"이라며 "문서화에 문제가 있는 프로젝트를 발견했을 때 담당자가 해결할 수 있도록 도와주고 개선 요청을 보내야 한다"고 강조했다.

IT전문 외신 더넥스트웹은 이같은 설문조사 결과를 보도하면서 “깃허브는 사용방법에 대한 설명이 부족한 프로젝트가 많다”며 이런 결과가 나온 것이 놀라운 일도 아니라고 보도는 지적했다. 그러면서, 문서화가 얼마나 중요한지 강조하는 기술분야 여러 인사들의 말을 소개했다.

관련기사

인기 있는 기술 블로거 마이크 포프(☞링크)는 제대로된 문서화의 중요성을 이렇게 말했다. “문서화되지 않은 것은 존재하지 않는다. 문서화 되어 있어 있는 것만으로는 부족하다. 설명해주고, 가르쳐주고, 시연해줘야 한다. 그렇게 하면 사람들은 당신의 문서가 아닌, 당신의 제품에 흥미를 가질 것이다.”

프로그래밍 정보 커뮤니티 스택오버플로 설립자 제프 앳우드(☞링크)도 문서화가 부실할 경우 애써 만들어 공개한 결과물이 무용지물이 될 수 있다며 아래와 같이 지적했다. “문서화가 부실하게 되어 있다면, 당신의 라이브러리가 얼마나 아름다운지, 또 얼마나 지능적으로 디자인되어 있는지는 중요하지 않게 된다. 당신만 이 결과물을 이해할 수 있다면, 어디에도 쓰일 수 없다. 문서화란 단지 자동생성된 애플리케이션프로그래밍인터페이스(API)만을 의미하지 않는다. 주석된 설명과 심도 있는 튜도리얼이 포함되어 있어야 한다. 사람들이 당신의 라이브러리를 쉽게 사용하길 원한다면, 이 3가지를 모두 충족시켜야 한다.”