Discord의 시니어 개발자 에반젤리스트 Colin Loretz가 문서를 누구나 기여할 수 있도록 '오픈'하고, 커뮤니티와 PR 중심으로 협업하며 얻은 교훈과 실질적 운영 노하우를 공유합니다. Discord는 오픈소스 제품은 아니지만, 문서는 공개된 GitHub 저장소에서 관리하며, 매달 30~50건의 PR 중 절반 이상이 커뮤니티에서 올라올 만큼 활발한 협업이 이루어지고 있습니다.
https://github.com/discord/discord-api-docs
1. 오픈 문서의 의미와 효과
- 문서를 오픈하면 개발팀과 사용자와의 '공동 창작' 및 '공동 소유' 관계가 형성됩니다.
- Discord는 공식 SDK 외에도 60개 이상의 커뮤니티 라이브러리(20개 이상 언어)를 지원하며, 이 생태계가 문서에 크게 의존합니다.
https://discord.com/developers/docs/developer-tools/community-resources
- 문서를 오픈하는 것은 단순히 '무료 노동'을 기대하는 것이 아니라, 팀이 커뮤니티와 함께 적극적으로 소통하고, 책임을 공유하는 것임을 강조합니다.
(발표 도중에 파티에 대한 비유를 자주 사용하는데, 그런 공개된 파티에 가본 적이 없어서 ㅠㅠ 하여간 파티를 연다고 모두가 찾아오는 것도 아니고 파티를 열었으면 호스트로서 게스트에 대한 책임을 다해야 한다고 합니다. 다른 소프트웨어 기업도 마찬가지지만 Discord 같은 경우 실제 사용자들이 무척 다양한 방식으로 사용하고 있기 때문에 그런 경험에 대해서는 개발팀에서 알 수 없고 설명하기 어려운 부분이라고 하네요. 그래서 그런 간격을 공개된 커뮤니티를 통해 채울 수 있다고 합니다).
2. 운영 방식과 도구
- 모든 문서는 마크다운(Markdown) 기반으로 GitHub에서 관리, PR·이슈·템플릿·자동화(링크나 스타일 체크, 마크다운 테이블 포맷 등) 도구를 적극 활용합니다.
- 자동화는 오타, 링크, 스타일 검사 등 기계가 잘하는 부분에 집중, 사람은 기술적 정확성·톤·맥락 등 심층 검토에 집중합니다.
- GitHub의 코드 오너(Code Owners), 팀별 리뷰 할당, Discord/Slack 알림, 미리 보기(Preview) 링크 등으로 기여 경험을 개선합니다.
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
3. 커뮤니티 기여 활성화 전략
- 명확한 기여 가이드(Contributing.md), PR/이슈 템플릿, 스타일가이드 등으로 초보자도 쉽게 참여할 수 있도록 설계합니다.
- FAQ, 튜토리얼 등 일부 문서부터 점진적으로 오픈해 운영 부담을 조절합니다.
- PR이 오래 방치되면 커뮤니티 신뢰가 떨어지므로, 신속한 피드백과 triage(분류) 시스템이 필요합니다.
(PR이 오래 방치되면 실제 제품과의 간격도 멀어지기 때문에 그 이력을 추적하기 어렵다고 합니다. 그럼에도 모든 PR을 다 제때 처리하는 것은 어렵다고 하네요).
4. 협업 과정에서의 교훈
- PR이 오래 열려 있으면 커뮤니티의 열의가 식으므로, '진행 중인 PR을 빠르게 처리'하는 것이 중요합니다.
- 모든 문서를 오픈할 필요는 없으며, 팀의 리소스와 전문성, 관리 가능 범위 내에서 단계적으로 확장할 수 있습니다.
- 자동화로 반복적/형식적 작업을 줄이고, 리뷰어는 필요한 피드백에 집중합니다.
- 커뮤니티와의 상호작용은 단순한 피드백을 넘어, 실제 제품 개선과 빠른 신기능 지원(예: Components v2)으로 이어짐.
https://github.com/discord/discord-api-docs/pull/7487
(피드백에 대해서 오타 같은 것을 사람에게 지적받으면 기분이 좋지 않을 수 있다고 합니다. 뭔가 무시당하는 느낌일 수도 있구요. 하지만 자동화를 통해 피드백을 받으면 맞춤법 검사기를 그냥 이용하는 것이니깐 그런 부담이 없다고 합니다. 그래서 그런 단순 실수에 대해서는 가능한 자동화를 통해 피드백을 준다고 하네요).
5. 실질적 조언 및 Q&A
- 오픈 문서 운영은 단순히 문을 열어두는 것이 아니라, '파티를 직접 주최하고 손님을 맞이하는 것'처럼 적극적 호스팅이 필요합니다.
- 민감한 정보, 출시 전 기능 등은 별도 비공개 브랜치/PR로 관리합니다.
(원칙은 모든 문서를 공개하고 같이 만든다는 것인데, 회사 정책 상 컨퍼런스 등에서 깜짝 공개하는 기술 같은 경우는 어쩔 수가 없다고 합니다).
- 초보 기여자는 Hacktoberfest 등 'good first issue'로 시작하면 좋습니다.
- 어떤 부분을 오픈할지, 어디까지 커뮤니티에 맡길지 명확히 결정하고, 리소스가 뒷받침되어야 합니다.
결론 및 메시지
- 문서를 오픈하는 것은 커뮤니티와 함께 성장하는 강력한 전략이지만, 팀의 적극적 참여와 명확한 프로세스, 자동화 도구, 신속한 피드백이 필수임을 강조합니다.
"Build with, not for" 즉, 커뮤니티와 함께 만들 때 진정한 시너지가 발생하며, 이는 제품·문서·생태계 모두에 긍정적 영향을 준다는 메시지로 발표를 마무리합니다.
13 Open Docs, Open Collaboratio - Colin Loretz
www.flickr.com
https://youtu.be/MFlGwC7DZqc?si=taQAccn9IzFoiGML
