Solomon
온보딩 문서는 신입이 쓰게 하라 — 아는 사람은 무엇이 빠졌는지 모른다
기존 구성원이 쓴 온보딩 문서에 빠지는 것들. 신입의 관찰을 문서로 회수하는 방법.
아는 사람은 빈틈을 못 본다
온보딩 문서를 오래된 구성원이 쓰면 반드시 빠지는 것이 있다. 너무 당연해서 적을 생각이 안 드는 것들이다.
- 그 저장소에 접근하려면 누구에게 권한을 요청하는가
- 로컬 실행에 필요한 환경 변수를 어디서 받는가
- 이 용어(내부 약어)가 무엇을 뜻하는가
- 슬랙 채널 중 어디가 실제로 살아 있는가
이런 것들은 모르는 사람만 발견할 수 있다. 그래서 문서의 빈틈을 메우는 가장 효율적인 방법은 신입에게 쓰게 하는 것이다.
구조
온보딩 첫 2주 동안 신입이 다음을 기록한다.
```markdown
막힌 것
- 어디서 막혔는지
- 어떻게 해결했는지 (또는 누구에게 물었는지)
- 문서 어디에 있었어야 하는지
```
2주 뒤 이 기록을 문서에 반영한다. 반영은 신입 본인이 하는 것이 좋다 — 아직 모르는 상태의 기억이 남아 있기 때문이다.
이 방식의 부수 효과: 신입의 첫 기여가 만들어진다. 코드를 몰라도 할 수 있고, 실제로 다음 사람에게 도움이 된다.
문서에 들어갈 것
절차만 있는 문서는 금방 낡는다. 맥락이 함께 있어야 오래 쓰인다.
| 항목 | 절차만 | 맥락 포함 |
|---|---|---|
| 배포 | "npm run deploy 실행" | "목요일에만 배포. 화요일 배포는 대응 인원 문제로 중단함" |
| 브랜치 | "feature/ 로 시작" | "main 직접 push 금지. CI가 main에서만 배포를 트리거하므로" |
| 리뷰 | "2명 승인 필요" | "1명은 해당 영역 담당자여야 함. 담당자 목록은 CODEOWNERS 참고" |
오른쪽은 왜 그런지가 있어서 예외 상황에서 판단할 수 있다.
사람 지도
기술 문서보다 유용한 경우가 많은 항목이다.
```markdown
누구에게 물어볼까
- 배포·인프라: 김 (슬랙 #infra)
- 결제 도메인: 박
- 디자인 시스템: 이
- 권한 요청: 최 (또는 #it-support)
```
신입이 가장 자주 막히는 지점이 "이건 누구에게 물어야 하나"이다. 이 목록 하나가 온보딩 속도를 크게 바꾼다.
진입점 하나
문서가 늘어나면 찾지 못하는 문제가 생긴다. 해결책은 문서를 줄이는 것이 아니라 진입점을 하나로 정하는 것이다.
```markdown
온보딩 시작
- 첫날: 계정·권한 (링크)
- 첫 주: 개발 환경 (링크)
- 둘째 주: 도메인 이해 (링크)
- 참고: 용어집 (링크) / 사람 지도 (링크)
```
이 한 페이지만 알려주면 나머지는 따라간다.
갱신 시점
문서가 낡는 것을 막는 현실적 방법은 갱신 시점을 이벤트에 묶는 것이다.
- 신입이 들어올 때 → 그 사람의 막힌 기록을 반영
- 절차가 바뀔 때 → 바꾼 사람이 문서도 수정
- 분기에 한 번 → 실행 명령이 여전히 동작하는지 확인
정기 점검만으로는 잘 안 된다. 신입 입사 시점이 가장 확실한 트리거다.
최종 수정 2026-08-28