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

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

와이어프레임에는 용어사전, 네트워크 정보, 릴리즈노트, API 문서, FAQ, 장애 런북, 배치 가이드가 한 화면에 다 올라가 있었다. 다 필요해 보였다. 그리고 유지보수 지옥이 보였다.

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

왜 ‘줄이기’부터 생각했는가 (이유)

반복 질문이 채팅창을 채울 때

팀장이 되고 나서 가장 많이 듣던 말이 있었다. ‘그거 어디 있어요?’ 배포 URL, DB 접속 정보, 특정 화면 분석 메모, 지난번 장애 때 뭐 했는지 — 답은 있었지만 한곳에 없었다. Notion에도 있고, 슬랙 스레드에도 있고, 누군가 머릿속에도 있었다.

문서를 한꺼번에 완성하려다 지쳤던 애자일·팀 성장 경험과 겹쳤다. 개발자센터도 ‘완성본’이 아니라 반복 질문이 오는 것부터 올리는 짧은 주기로 가야 했다.

넣고 싶었지만 빼야 했던 것

넣고 싶었던 목록은 길었다. 빼야 했다고 느낀 것도 분명했다.

이미 Notion에 잘 정리된 협업 문서 — 옮기기만 하면 두 군데 관리가 된다.
자주 바뀌는 임시 메모 — 올리는 순간부터 틀린 문서가 된다.
개인별 실험 기록 — 팀 기준이 아니라 혼란만 늘린다.
중복된 스크린샷 자료 — 찾기는 쉬워도 갱신은 안 된다.

기준을 이렇게 잡았다 (당시 결론)

반복 질문이 오는가 — 한 달에 두 번 이상 같은 질문이면 후보.
장애/배포 시 바로 찾는가 — 새벽에 검색되지 않으면 의미가 없다.
자동화로 갱신 가능한가 — 사람 손만 믿으면 결국 낡는다.
오프라인 문서를 대체하는가 — 종이·공유 폴더를 줄이는 게 1차 목표였다.

이 기준을 통과한 것만 올리기로 했다. 늘리는 결정보다 줄이는 결정이 더 어렵고 더 중요했다.

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

Jira·Confluence·Slack을 들였다가, 이후 Discord·Notion 중심으로 옮기면서 같은 질문을 반복했다. ‘이 도구가 없으면 반복되는 질문/수작업이 무엇인가’ — 개발자센터 필터가 그대로 협업 도구 선정 기준이 됐다.

좋아 보이는 기능을 다 켜면, 도구가 일을 줄여주는 게 아니라 도구를 관리하는 일이 새로 생겼다. 소프트웨어 선정 때도 같은 갈림길이었다. 호기심과 ‘지금 팀이 감당 가능한가’가 부딪혔다.

당시 결론: 꼭 필요한 채널·문서만 남기고 과감히 닫았다. 습관은 남기고 도구만 바꾼 셈이다.

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

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

앞으로 나가야 할 방향

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

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