코드가 심장이라면 문서는 목소리입니다.

안녕하세요, 괴짜 여러분? 오픈 소스 소프트웨어의 핵심이 코드라면, 문서화는 목소리입니다. 여러분의 프로젝트가 세상과 소통하는 방식입니다.

아무도 사용법을 알아내지 못해 훌륭한 프로젝트가 사장되는 것을 본 적이 있습니다. 문서가 없으면 코드는 그냥... 소음일 뿐입니다.

무엇이 문서를 훌륭하게 만드는가?

좋은 문서는 획일적인 것이 아닙니다. 그것은 시스템입니다. 최소한 다음이 필요합니다:

• 사용자 가이드 → 신규 입사자가 업무에 적응할 수 있도록 도와주는 온보딩 환경입니다.
• API 문서 → 프로젝트를 통합하려는 개발자를 위한 생명줄입니다.
• 기여 가이드 → 협업을 촉진하는 커뮤니티 플레이북.

이러한 기능이 없으면 프로젝트는 앞면에 그림이 없는 퍼즐 상자를 누군가에게 건네는 것과 같습니다.

문서가 채택의 성패를 좌우하는 이유

모든 문제를 해결할 수 있는 오픈소스 도구를 발견했다고 상상해 보세요. 흥분됩니다. 설치합니다. 그리고... 귀뚜라미. 지침도, 예제도 없고 "행운을 빕니다"라는 사용 설명서만 있습니다.

당신은 튕깁니다. 모두가 그렇습니다.

React나 다른 오픈소스 강자들을 보세요. 그들의 문서는 코드만큼이나 세련되어 있습니다. 그건 우연이 아닙니다. 명확한 문서는 사용자를 도울 뿐만 아니라 지지자를 만들기도 합니다. 개발자가 벽에 부딪히지 않고 라이브러리에 플러그인할 수 있다면 개발자는 소문을 퍼뜨립니다.

어려운 부분: 문서 작성 및 업데이트

네, 문서 작성은 어렵습니다. 필요하죠:

• 전문 용어 없는 명료성
• 말뿐 아니라 보여주는 예시
• 사람들이 빠르게 답을 찾을 수 있는 논리적 구조

하지만 가장 어려운 부분은? 문서를 최신 상태로 유지하는 것입니다. 오래된 문서는 아예 없는 것보다 못합니다. 마치 3년 전에 문을 닫은 업체로 안내하는 GPS를 사용하는 것과 같습니다. 답답하죠.

문서 건너뛰기, 프로젝트 가라앉히기

문서화만으로는 개발자 모임에서 좋은 점수를 받을 수 없습니다. 하지만 문서가 없으면 모래 위에 건물을 짓는 것과 같습니다. 문서는 다른 모든 것의 토대입니다.

그러니 작성하세요. 유지하세요. 다듬으세요. 코드가 살아 있으려면 문서가 말을 해야 합니다.

다음 단계: E는 수명 종료

다음 편에서는 좋은 소프트웨어의 수명이 다하는 E에 대해 알아보고, 왜 관심을 가져야 하는지에 대해 이야기할 OSS의 ABC를 기대해 주세요.

그때까지는요? 코드를 깔끔하게 정리하고 문서를 더욱 깔끔하게 유지하세요.

‍