오픈소스의 문서가 부실한 이유와 방대한 이유

PHP 와 Node.js 생태계에서 개발하면서 문서가 너무 없거나, 너무 많아서 원하는 내용을 찾기 힘든 경우가 많았다.

1. 문서가 부실한 이유: "개발자의 딜레마와 현실"

오픈소스가 문서화보다 기능 구현에 쏠릴 수 밖에 없는 원인 

The Code is Truth

코드를 작성한 사람은 코드의 흐름을 너무 잘 알고 있을 것이다. 그래서 주석이나 문서 없이도 변수명과 함수 구조만 보면 잘 안다. 프로그래밍 언어 특성에 따라 자바스크립트 생태계는 코드를 빨리 짜고 배포하는 문화가 강하다. "일단 동작하게 만드는 것(Make it work)"이 우선시되다 보니 문서는 뒷전으로 밀리는 것 같다. 이로인해 `README.md`에 설치 방법만 있고, 구체적인 사용법이나 엣지 케이스에 대한 설명이 없는 경우가 많은 것 같다. 

1인 메인테이너의 리소스 한계

인기 있는 패키지조차 알고 보면 퇴근 후 짬을 내어 관리하는 1~2명의 개발자에 의해 유지되는 경우가 많다. 그 대표적인 예시로는 데니스 푸시카레프(Denis Pushkarev)의 core-js 라고 불리는 풀리플(Polyfill)가 아닐까 싶다. 

소수 인원이 관리할 경우 기능 버그 수정과 이슈 대응(Issue tracking)만으로도 벅차다. 기술 문서를 작성하고 최신화하는 것은 엄청난 시간과 글쓰기 능력을 요구하는 일이라 우선순위에서 밀리기 마련이다.

빠른 버전 변동 (Version Churn)

Node.js/NPM 생태계의 변화는 너무 빠르다. 문서를 공들여 써놔도 6개월 뒤 메이저 버전이 업데이트되면 이 문서는 신뢰를 잃게 된다. 문서를 현행화하는 속도가 코드 변경 속도를 따라가지 못해, 결국 문서를 포기하거나 "소스 코드를 참조하세요"라고 남겨두게 된다. 

2. 문서가 지나치게 방대한 이유: "정보의 홍수와 파편화"

반대로 정보가 너무 많아 필요한 내용을 찾기 힘든 경우도 있다. 이는 주로 '성숙도'와 '커뮤니티' 때문인것 같다. 

역사가 깊은 생태계 (Legacy Accumulation)

PHP는 역사가 길어서 구글링을 제이쿼리와 SOLID 원칙이 대중화가 되지 않았던 옛날 자료와 2020년 이후의 자료(Modern PHP 8.x, Laravel)가 섞여서 나온다. 주니어는 어떤 것이 Best Practice 인지 구분하기 어렵다. 구글 검색 결과의 상단에 노출되는 과거의 인기 글, 지금은 안티패턴이 되어버린 글이 나올 경우 있어 정보의 양은 많지만 원하는 정보를 찾는데 발생하는 비용은 높게 나온다. 

파편화된 해결책 (Fragmentation)

Node.js 는 "작은 것이 아름답다"는 철학 아래 너무 많은 마이크로 패키지들이 존재한다.

같은 기능을 하는 라이브러리가 수십 개(날짜 라이브러리로 Moment, Day.js, Luxon, Date-fns 등) 존재하며, 각자 방대한 문서를 가지고 있다. 개발자는 문제를 해결하는 시간보다, 어떤 라이브러리가 최신이며 문서를 잘 갖춰지고, 경량화되어있고, 성능은 누가 더 좋은지, Star 는 뭐가 더 많은지 '비교 분석'하는 데 더 많은 시간을 투자하게 된다. 

자동 생성 문서의 함정 (Generated Docs)

PHPDoc, JSDoc, Swagger 등을 이용해 API 문서를 자동 생성해두는 경우가 많다. 

함수 이름과 파라미터 타입만 나열된 문서는 양적으로는 방대해 보이지만, "그래서 이걸 언제, 어떻게 조합해서 써야 하는데?"  라는 내용을 정확하게 전달하지 못한다. 기계적인 정보량만 많고 실질적인 학습 가치는 낮은 경우도 다반사다.

3. PHP vs Node.js

	PHP 생태계의 문서 특징	Node.js 생태계의 문서 특징
공식 문서	php.net 은 사용자 댓글까지 포함된 집단지성의 산물로, 웬만하면 공식 문서에서 해결됨.	API 명세 위주 nodejs.org 문서는 친절하기보다는 기술적 명세서에 가까워 주니어가 읽기 어려움.
오픈소스	프레임워크 중심으로 Laravel, Symfony 등 프레임워크는 상용 수준의 완벽한 문서를 제공함. 그 외 소규모 라이브러리는 양극화 심함.	마이크로 모듈 중심으로 수백만 개의 패키지가 존재하며, README 한 장짜리 패키지부터 완벽한 문서까지 퀄리티 격차가 매우 큼.
검색	오래된 레거시 정보를 걸러내는 능력이 필요함.	사라지거나 관리 안 되는(Deprecated) 라이브러리를 구분하는 능력이 필요함.

 

단순히 문서를 읽는 것이 아니라 전번적인 히스토리로 문서의 작성 시점(Last updated), 메인테이너의 활동성(Commit frequency), 커뮤니티의 반응(Issues/Stars) 등을 보고 판단해야한다.
문서가 부실하다고 불평하는 것을 넘어, 내가 겪은 시행착오를 PR(Pull Request)로 보내거나 블로그에 정리해서 생태계를 건강하게 만드는 태도가 중요하다.