가독성 검사를 하며 문장 길이만 줄이면 독자가 무엇을 해야 하는지는 여전히 안 보일 수 있습니다. 짧은 선언 다섯 개를 늘어놓는 것과 하나의 과업을 순서대로 설명하는 것은 다릅니다. 기술 글에서는 읽기 지표보다 독자가 다음 행동을 알 수 있는지, 실패했을 때 어디로 돌아갈지, 완료를 어떻게 확인할지를 먼저 봅니다.
99자 문장 하나를 4개 행동으로 나뉘었습니다.
기존 예문은 자료를 정리하면 업무가 빨라지고 오류가 사라진다는 평가를 98자 한 문장에 담았습니다. 수정본은 원본 복사·행 수와 ID 비교·불일치 시 중단·성과 미보장의 네 문장으로 나뉘었습니다.
| 항목 | 수정 전 | 수정 후 |
|---|---|---|
| 문장 수 | 1 | 4 |
| 평균 문장 길이 | 98자 | 18.8자 |
| 가장 긴 문장 | 98자 | 37자 |
| 실행 단계 | 없음 | 복사→비교→중단 |
독자의 과업을 한 장에 그려 봅니다.
- 시작 조건을 적습니다. 필요한 파일·권한·버전을 빼먹지 않습니다.
- 각 단계의 완료 결과를 명사로 적습니다. 예: “행 수가 적힌 비교표”.
- 실패 신호와 되돌리기 위치를 같이 놓습니다.
- 마지막에 완료 판정을 넣습니다. 예: “ID 열의 문자열이 전부 일치”.
모바일에서는 “검사표를 보기 전에 핵심”이 있어야 합니다.
표가 가로로 길면 독자는 판정 기준을 읽기 전에 스크롤하다 떠날 수 있습니다. 표 앞에 “무엇을 비교하는지”를 한 문장으로 쓰고, 표 뒤에 판단 결과를 바로 놓습니다. 스크린 리더가 헤더를 올바르게 읽는지, 360px에서 코드·표·다운로드가 잘리지 않는지도 문장 길이 측정과 따로 확인합니다.
이 글의 재현 자료
전체 자료의 범위·실행 방법·주의사항은 재현 자료 안내에서 한번에 확인할 수 있습니다.
원문과 함께 읽기
소제목은 주제가 아니라 결과를 알려 줍니다.
“준비”, “실행”, “주의사항”만 놓으면 독자는 어느 구간에 원하는 해답이 있는지 알기 어렵습니다. “ID 열을 문자열로 고정합니다”, “불일치가 있으면 쓰기를 멈출니다”처럼 해당 구간에서 완료할 일을 소제목에 넣습니다. 독자는 전체를 순서대로 읽기 전에도 필요한 구간을 찾을 수 있습니다.
첫 문단에는 이 글이 해결하는 문제와 해결하지 않는 범위를 함께 적습니다. 파서가 문자열을 보존하는지 검사하는 글이라면, 스프레드시트 제품별 보안까지 보장하지 않는다는 한계를 앞에 놓습니다. 면책 구간에만 숨기면 실행 단계에서 오해가 생깁니다.
용어는 처음 한 번만 풀고, 뒤에서 바꾸지 않습니다.
| 문제 | 독자가 겪는 일 | 편집 방법 |
|---|---|---|
| 동의어 남발 | 같은 개념을 새 개념으로 오해 | 표준 용어 하나를 고정 |
| 약어 먼저 사용 | 첫 단계부터 멈춤 | 처음에 원말과 의미를 함께 표시 |
| 한글·영어 섞음 | 검색할 단어를 모름 | 화면 용어와 코드 용어를 함께 표시 |
| 판정 상태 혼용 | 실패·보류·미확인을 구분하지 못함 | 상태별 다음 행동을 적음 |
용어표는 글의 길이를 늘리기 위한 장식이 아닙니다. 독자가 다음 단계를 잘못 선택할 수 있는 용어만 정리합니다.
디자인 검수는 문장 검수와 따로 합니다.
- 360·390·430px에서 제목·표·코드·다운로드가 잘리지 않는지 봅니다.
- 768px에서 표의 스크롤 범위와 목차 배치를 확인합니다.
- 1440·1600·1920px에서 줄 길이가 지나치게 늘어나지 않는지 봅니다.
- 키보드만으로 메뉴·링크·도구·세부 결과에 도달할 수 있는지 확인합니다.
- 표지는 개념 이미지라고 캡션에 표시하고, 실제 증거가 필요한 자리에는 원본 캡처를 사용합니다.
매끄럽게 보이는 것은 가독성의 한 부분입니다. 시각적으로 완성도가 높아도 독자가 실패를 판단할 수 없거나 다음 행동을 찾지 못하면 기술 가이드의 목적을 달성하지 못한 것입니다.
