
개발 협업에서 설명을 마쳤는데도 같은 질문이 돌아온다면, 먼저 상대에게 빠진 정보가 무엇인지 확인해 볼 수 있다. 팀 안에서 익숙한 약어와 작업 순서는 새로 합류한 사람에게는 처음 보는 규칙일 수 있다.
구글의 기술 글쓰기 교육은 독자가 과업을 수행하는 데 필요한 지식과 이미 알고 있는 지식의 차이를 고려하라고 안내한다. 전문가가 초보자도 자신과 같은 배경을 알 것이라고 가정하기 쉬운 문제도 다룬다. 이 관점을 기술 설명에 적용하면 말을 더 짧게 하는 것과 실행에 필요한 정보를 빼는 것을 구분할 수 있다.
먼저 누구를 위한 설명인지 적기
같은 개발자라도 프로젝트에 처음 온 사람과 해당 기능을 관리해 온 사람에게 필요한 설명은 다르다. 문서 첫머리에 읽는 사람과 작업의 목적을 적어 보자.
예를 들어 새로 합류한 기획자가 테스트 서버에서 장비 수치를 확인하는 문서라면, 서버 이름만 쓰는 것으로는 부족할 수 있다. 접근 권한을 받는 경로, 확인할 데이터, 수정해도 되는 범위가 필요하다. 운영 환경을 변경할 수 있는 사람을 위한 문서와는 시작 조건부터 달라진다.
당연해 보이는 한 문장을 풀어 쓰기
다음은 이 글에서 만든 가상의 인수인계 예시다.
부족한 안내: 최신 빌드로 확인하고 이상하면 로그를 보내 주세요.
| 항목 | 보완한 안내에 포함할 내용 |
|---|---|
| 준비 | 테스트 계정 권한과 대상 빌드 식별자 |
| 작업 위치 | 테스트 환경 이름, 접속 경로, 확인할 장비 자료 |
| 실행 | 바꿀 항목과 저장 후 다시 열어 볼 화면 |
| 완료 상태 | 어떤 값이 어디에 표시되면 확인이 끝나는지 |
| 문제 기록 | 재현 순서, 발생 시각, 실제 결과와 기대 결과 |
| 전달 범위 | 담당자와 공유 경로, 개인정보·비밀값을 제외하는 기준 |
모든 설명에 긴 표를 붙일 필요는 없다. 다만 상대가 아직 모르는 항목은 문장이나 연결 문서로 보충해야 한다. 반대로 이미 아는 준비 과정을 매번 반복하면 정작 중요한 변경을 찾기 어려울 수 있다.
전달 여부를 작은 실행으로 확인하기
설명 끝에 이해했는지만 묻기보다, 다음에 할 일을 상대가 정리해 보도록 요청할 수 있다. 테스트 환경과 운영 환경을 혼동했다면 접근 대상을 다시 설명하고, 완료 조건이 모호했다면 확인할 결과를 고친다. 이는 이 글에서 제안하는 협업 점검 방식이다.
문서 검토에서도 작성자가 옆에서 모든 단계를 대신 설명하면 빈틈을 발견하기 어렵다. 처음 읽는 사람이 문서만으로 작업을 시작해 보고, 멈춘 위치와 새로 물어본 내용을 기록하면 보완할 부분이 드러난다. 실행 실패가 권한이나 환경 문제라면 설명 문구만 바꾸는 데 그치지 말고 해당 조건도 해결해야 한다.
이렇게 찾은 빈칸을 문서에 채워 두면, 다음에 합류한 사람은 같은 곳에서 멈추지 않고 작업을 시작할 수 있다.
참고 자료
- Google, Technical Writing One — Audience