개발자센터, 무엇을 넣고 무엇은 빼야 할까

개발자센터를 만들기로 했을 때, 처음엔 거창했다. 모든 걸 여기에.

일주일 뒤, 현실은 더 단순했다. 무엇을 넣어야 운영이 줄어드는가.

넣고 싶었던 것

• 용어사전
• 네트워크 정보
• 릴리즈노트
• API 문서
• FAQ
• 장애 대응 런북
• 배치 실행 가이드

다 필요해 보였다. 그래서 유지보수 지옥이 보였다.

빼야 했다고 느낀 것

• 이미 Notion에 잘 정리된 협업 문서
• 자주 바뀌는 임시 메모
• 개인별 실험 기록
• 중복된 스크린샷 자료

기준을 이렇게 잡았다

1. 반복 질문이 오는가
2. 장애/배포 시 바로 찾는가
3. 자동화로 갱신 가능한가
4. 오프라인 문서를 대체하는가

이 기준을 통과한 것만 올리기로 했다.

비슷한 경험 — 협업 도구를 갈아탈 때

이 “무엇을 넣고 무엇을 뺄까”의 고민은 협업 도구를 도입·교체할 때도 똑같았다. Jira·Confluence·Slack을 들였다가, 이후 Discord·Notion 중심으로 옮기면서 같은 질문을 반복했다.

• 이유: 좋아 보이는 기능을 다 켜면, 도구가 일을 줄여주는 게 아니라 도구를 관리하는 일이 새로 생겼다. 새 도구에 대한 호기심과 “지금 팀이 감당 가능한가”라는 현실이 또 부딪혔다.
• 당시 결론: “이 도구가 없으면 반복되는 질문/수작업이 무엇인가”를 기준으로, 꼭 필요한 채널·문서만 남기고 과감히 닫았다. 개발자센터의 필터 기준이 그대로 협업 도구 선정 기준이 됐다.
• 도구든 문서든, 핵심은 늘 같았다. 늘리는 결정보다 줄이는 결정이 더 어렵고 더 중요하다.

아직 고민 중인 것 (개선점)

• API 문서를 어디까지 자동 생성할지 — 수기 문서는 반드시 코드와 어긋난다. 하지만 전부 자동화하면 맥락 설명이 빠진다.
• 릴리즈노트를 누가 언제 갱신할지 — 책임자가 없으면 결국 아무도 안 쓴다.
• FAQ와 런북의 경계를 어디에 둘지 — 둘이 섞이면 장애 때 정작 필요한 절차를 못 찾는다.
• 올린 문서의 수명 관리가 없다. 오래돼 틀린 문서가 새 문서보다 위험할 때가 있다.

앞으로 나가야 할 방향

1. API 문서는 자동 생성(스펙) + 사람이 쓰는 맥락(가이드) 을 분리해, 자동화와 설명을 둘 다 살린다.
2. 릴리즈노트·런북에 갱신 책임자와 주기를 명시해, “누가 언제”를 구조로 박는다.
3. 문서마다 최종 검토일을 붙이고, 오래된 문서는 자동으로 ‘점검 필요’ 표시가 뜨게 한다.
4. 반복 질문 데이터를 모아, 무엇을 FAQ로 승격할지를 감이 아니라 빈도로 결정한다.

개발자센터는 완성품이 아니라, 운영 부담을 줄이는 필터에 가깝다고 느끼고 있다. 다음 목표는 그 필터가 한 번 만든 뒤 방치되지 않도록, 스스로 낡음을 알려주는 구조로 만드는 것이다.