문서의 설정 파일은 새 운영자에게 없었다
가상 이야기 · 핵심노트 기반
핵심노트 개념: 검토와 사용 시험 — 처음 읽는 사람도 따라 할 수 있는지 확인한다
이 글에서 배우는 교훈
문서의 사용 시험은 처음 읽는 사람이 실제로 수행하며 멈추는 조건을 찾고 수정 후 다시 확인하는 과정입니다.
핵심노트를 바탕으로 만든 가상 이야기입니다. 실제 사건이나 검증된 성과가 아닙니다.
근거: 검토와 사용 시험 — 처음 읽는 사람도 따라 할 수 있는지 확인한다 · 핵심노트 19
구체적으로는 새 운영자에게 없던 설정 파일의 준비 경로를 추가하고 빈 환경에서 다른 독자의 실행으로 재검증했습니다.
관련 교재 내용
프로젝트관리 및 테크니컬커뮤니케이션 · IV. 테크니컬 문서 · 리뷰와 적합성
교재는 리뷰로 정확성·논리성을 점검하고 독자의 사용 목적에 맞게 작성하도록 설명합니다.
이 사례에 적용한 내용: 새 운영자에게 없던 설정 파일의 준비 경로를 추가하고 빈 환경에서 다른 독자의 실행으로 재검증했습니다.
교재 원리의 실무 적용 · 교재 원문 인용이 아닌 자체 설명입니다.
본문
작성자는 설치 문서대로 실행하면 서비스가 열린다고 생각했습니다. 새 운영자에게 아무 설명 없이 따라 해 보게 하니 설정 파일을 찾지 못해 첫 실행에서 멈췄습니다. 작성자 PC에는 예전에 받은 파일이 이미 있어서 문서에 빠진 것을 몰랐습니다.
작성자는 설정 파일을 받는 승인 경로와 놓을 위치, 올바른 환경인지 확인할 항목을 추가했습니다. 비밀 값 자체는 문서에 쓰지 않았습니다. 다른 새 운영자가 빈 시험 환경에서 다시 따라 해 시험 요청까지 성공하는지 확인했습니다.
결론
문장만 읽어 검토할 때는 작성자의 경험이 빠진 단계를 채워 버릴 수 있습니다. 실제 독자의 수행을 관찰하고 수정 뒤 다시 확인해야 문서가 혼자서도 쓰이는지 알 수 있습니다.