온보딩 문서에 도구와 권한의 연결 관계 담기

신규 엔지니어를 위한 온보딩 문서를 준비하면서, 평소 사용하던 도구가 생각보다 많다는 것을 다시 느꼈습니다. 저장소를 받고 개발 도구를 설치하는 순서만 적어서는 서비스를 실행하거나 문제를 확인하는 데까지 이어지지 않았습니다.

소스 코드, 시크릿, 클라우드 접근, 배포, 로그 조회가 각각 다른 시스템에 나뉘어 있었습니다. 각 도구에 들어갈 수 있는지와 실제 업무에 필요한 권한이 있는지도 따로 확인해야 했습니다.

도구 접근과 업무 권한의 차이

로그 플랫폼에 로그인할 수 있어도 필요한 인덱스를 조회할 수 없으면 운영 중인 서비스의 로그는 볼 수 없습니다. 같은 도구 안에서도 팀이나 환경에 따라 접근 범위가 달랐습니다.

저장소 접근 권한을 받았지만 실행에 필요한 시크릿을 읽을 수 없는 경우도 있습니다. 문서에 적힌 실행 명령이 맞더라도, 앞 단계의 권한이 준비되지 않았다면 다음으로 넘어갈 수 없습니다. 이런 상황에서는 명령어를 다시 설명하는 것보다 어떤 접근 권한이 빠졌는지 확인할 수 있게 해주는 편이 도움이 됩니다.

개발 흐름에 따른 문서 구성

도구를 하나씩 나열하기보다 서비스를 받아서 실행하고, 변경을 배포하고, 결과를 확인하는 순서에 맞춰 설명하려고 했습니다.

이렇게 묶으면 신규 입사자가 지금 필요한 도구부터 볼 수 있습니다. 도구의 전체 기능을 익히기 전에, 자신이 하려는 작업이 어떤 시스템을 거치는지 알 수 있도록 하는 구성입니다.

권한 신청의 선행 조건

접근 신청에는 승인이나 그룹 가입처럼 먼저 끝나야 하는 절차가 있었습니다. 따라서 설치 단계에 도달한 뒤 권한을 신청하게 하기보다, 미리 준비할 항목을 앞에서 안내할 필요가 있었습니다.

신청 링크와 함께 권한의 용도, 필요한 팀·환경 범위, 승인 후 확인 방법을 적는 방식이 좋겠다고 생각했습니다. 특정 화면에 로그인됐다는 사실만으로 준비가 끝났다고 판단하지 않도록, 실제로 필요한 작업까지 가능한지 확인하는 설명도 필요했습니다.

유지할 수 있는 문서 범위

모든 도구의 사용법을 온보딩 문서에 복사하면 관리할 내용이 너무 많아집니다. 상세 설정은 각 도구의 공식 내부 문서로 연결하고, 온보딩 문서에는 팀에서 필요한 순서와 접근 범위를 남기는 편이 낫습니다.

문서를 준비하며 정리하고 싶었던 것도 이 부분이었습니다. 처음 합류한 사람이 어느 도구부터 봐야 할지, 어디까지 권한을 받아야 할지, 막혔을 때 누구에게 물어봐야 할지 알 수 있는 문서였습니다.