신규 입사자 첫 주, 무엇을 먼저 읽게 할 것인가

읽히지 않는 위키는 없는 것과 같다

팀에 새 사람이 들어올 때마다 반복되는 질문이 있다. “어디서부터 읽어야 해요?” 위키 페이지가 340개인데 입구가 없다. 지난번 합류자는 첫 이틀을 Confluence 검색창 앞에서 보냈다고 했다. 그게 나쁜 사람 문제가 아니라 구조 문제라는 걸 한참 뒤에야 인정했다.

막상 손대보니 문제는 ‘분량’이 아니었다. 순서가 없었다. 모든 페이지가 동등한 권위를 갖고 나란히 놓여 있었다. 첫 주에 읽어야 할 것과 3개월 뒤에나 필요한 것이 같은 카테고리 안에 섞여 있었다.

Day 1 — 맥락 먼저, 도구는 나중

입사 첫날 계정 세팅보다 먼저 줘야 할 게 있다. ‘이 팀이 왜 존재하는가’에 대한 한 페이지짜리 문서다.

팀 존재 이유, 지금 풀려는 문제, 지표 세 가지를 한 페이지에. 우리는 올해 이걸 처음 만들었는데, 기존 팀원 두 명도 “이런 게 있었으면 좋았을 텐데”라고 했다. 입사자 용이 아니라 팀 전체에 필요했던 문서였다.
서비스 아키텍처 다이어그램 최신본. 단, 날짜가 찍혀 있어야 한다. 날짜 없는 다이어그램은 신뢰할 수 없다. 6개월 전 그림이 지금도 메인 페이지에 걸려 있으면 첫날부터 혼란이 시작된다. 실제로 한 신규 합류자가 이미 deprecated된 서비스에 첫 PR을 올린 사례가 있었다.
온콜 담당자 명단과 에스컬레이션 경로. 뭔가 터졌을 때 누구한테 말해야 하는지를 첫날에 알아야 한다. 이걸 몰라서 DM을 잘못 보내고 1시간을 허비한 적이 있다.

Day 2~3 — 운영 매뉴얼 한 벌

코드를 읽기 전에 장애 대응 흐름을 먼저 보여준다. 이 순서가 반대였을 때 문제가 생겼다.

최근 6개월 이내 postmortem 두 편. 이게 가장 빠르게 팀 문화를 전달한다. 어떤 식으로 장애를 분석하고, 어디까지 솔직하게 적는지가 문서 하나에 다 들어 있다. 우리는 postmortem을 사건 후 72시간 안에 작성하는 걸 목표로 하는데, 실제 평균은 아직 5일이다. 그 솔직함도 같이 전달된다.
배포 프로세스 한 장 요약. CI 파이프라인 구조, 브랜치 전략, 롤백 트리거 조건. 분량이 긴 가이드 문서 링크는 나중에. 첫 주에는 “이것만 보면 배포할 수 있다”는 한 장이 훨씬 유용하다. 실제로 6페이지짜리 배포 가이드를 줬을 때, 합류자가 처음 배포를 스스로 하기까지 열흘이 걸렸다. 한 장 요약을 줬을 때는 사흘이었다.
알람 항목 목록과 각 알람의 임계값 의미. Prometheus 룰이 37개인데 이걸 다 볼 필요는 없다. “이 알람이 울리면 이게 문제다”를 10개만 추려서 넘긴다.

Day 4~5 — 코드 진입점 딱 하나

“코드 읽으세요”는 지시가 아니다. 어디서 시작하는지를 짚어줘야 한다.

핵심 서비스 레포지토리 한 개, README의 ‘Getting Started’ 섹션. 우리는 올해 초 README 첫 줄에 “담당자: @mings / 백업: @jake”를 박았다. 질문을 어디로 보내야 하는지를 코드 옆에 붙여두는 것만으로도 첫 주 슬랙 DM이 눈에 띄게 줄었다.
주요 API 엔드포인트 목록과 각각 어떤 팀이 consume하는지. 신규 합류자가 엔드포인트를 잘못 수정했다가 다른 팀 서비스가 500을 뱉은 사건이 있었다. 의존 관계를 한 줄이라도 적어두는 것과 아닌 것의 차이는 생각보다 크다.
로컬 환경 세팅 스크립트 + 마지막 성공 실행 날짜. 스크립트가 있어도 6개월 묵으면 동작 안 한다. 날짜를 CI에서 자동 갱신하도록 붙여두니 신뢰도가 올라갔다.

절대 첫 주에 주지 않는 것

자료를 고를 때 ‘뭘 줄까’만큼 ‘뭘 안 줄까’가 중요하다.

전사 정책 문서 전체. 취업 첫날 취업규칙 PDF 100페이지를 읽는 사람은 없다. HR 공지는 2주 차 이후로 미룬다.
역사적 맥락 문서. “원래 이 서비스가 왜 만들어졌냐면…” 류의 배경 설명은 첫 주에 오히려 노이즈다. 3개월 뒤에 직접 물어보게 두는 게 낫다.
아직 결론 안 난 RFC. 진행 중인 설계 논의를 첫 주에 읽히면 혼란만 생긴다. “이게 지금 어느 방향인 거예요?”라는 질문이 들어오면 누군가가 30분을 맥락 설명에 써야 한다.

다음 한 가지

다음 합류자가 들어오기 전에, ‘첫 주 읽기 목록’을 별도 페이지로 분리해서 링크 한 줄로 전달할 수 있게 만든다 — 그리고 그 다음 글에서 진짜 했는지 한 줄 적는다.

🛒 이 글과 어울리는 추천 상품

위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.