개발기초 신입 개발자 온보딩 문서 만들며 겪은 시행착오 (실제로 도움 됐던 방식)

MES 스마트 팩토리 에 신입 개발자가 새로 합류하게 되면서, 온보딩 문서를 처음부터 만들게 된 적이 있습니다. "그냥 아는 거 정리하면 되겠지"라고 쉽게 생각했는데, 막상 써보니 생각보다 훨씬 어려운 작업이었습니다.

상황: 왜 온보딩 문서가 필요했나

그동안은 신입이 들어오면 옆자리 선배가 구두로 설명해주는 방식이었는데, 설명해주는 사람마다 내용이 조금씩 다르고 빠지는 부분도 있어서 신입 적응 속도가 매번 들쭉날쭉했습니다. 이걸 개선하려고 문서화를 시작했습니다.

문제 1: 내가 당연하게 아는 걸 문서에 빠뜨렸다

처음 초안을 다 쓰고 신입 개발자에게 줬는데, 예상보다 훨씬 많은 질문이 돌아왔습니다. 제 입장에서는 "당연히 아는 것"이라 문서에 아예 적지 않은 부분들이었습니다.

예: [로컬 개발 환경 세팅 시 특정 포트가 이미 다른 프로세스에서 쓰이고 있을 때 대처법 / 사내 VPN 연결 순서]

해결: 이후로는 문서를 쓸 때 "내가 처음 입사했을 때 뭐가 헷갈렸는지"를 먼저 떠올리고, 그 기준으로 다시 작성했습니다. 또한 신입이 실제로 문서를 보면서 세팅을 따라 하게 하고, 막히는 지점을 그 자리에서 바로바로 문서에 추가하는 방식으로 보완했습니다.

문제 2: 문서가 금방 오래된 정보가 되었다

몇 주 뒤에 다시 보니, 그 사이 바뀐 배포 절차나 새로 추가된 도구가 반영이 안 되어 있었습니다. 신입이 오래된 문서를 보고 따라 하다가 오히려 혼란스러워한 적도 있었습니다.

해결: 온보딩 문서를 "한 번 만들고 끝"이 아니라, [스프린트마다 / 신입이 새로 들어올 때마다] 검토하는 일정으로 정해뒀습니다. 특히 새로 들어온 신입에게 "이 문서에서 이상하거나 안 맞는 부분 있으면 바로 알려달라"고 부탁해서, 최신 상태를 유지하는 책임을 분산시켰습니다.

문제 3: 정보량이 너무 많아서 신입이 오히려 부담스러워했다

의욕이 앞서서 회사 조직도부터 배포 절차, 코딩 컨벤션까지 한 문서에 다 몰아넣었더니, 신입 입장에서는 첫날부터 정보량에 압도된다는 피드백을 받았습니다.

해결: 문서를 "첫날에 꼭 봐야 하는 것"과 "적응하면서 천천히 봐도 되는 것"으로 나눠서 단계별로 구성했습니다. 첫날은 로컬 환경 세팅과 기본 커뮤니케이션 채널 정도만 다루고, 나머지는 이후 주차별로 순서를 정해서 안내했습니다.

마무리하며

온보딩 문서를 만들면서 느낀 건, **좋은 문서는 "다 아는 사람이 쓴 문서"가 아니라 "처음 보는 사람의 눈높이에서 다시 쓴 문서"**라는 점이었습니다. 제가 당연하다고 여기던 지식이 실제로는 전혀 당연하지 않다는 걸 이 과정에서 많이 배웠습니다.

새로운 팀원을 맞이할 준비를 하고 계신 분들이라면, 문서를 혼자 완성하려 하지 마시고 신입이 실제로 따라 해보게 하면서 함께 다듬어나가시는 걸 추천합니다.