구체적으로 쓰기
모호하거나 불필요하게 장황한 표현은 독자의 이해를 방해하고, 중요한 정보를 빠르게 파악하기 어렵게 만들어요. 특히 기술 문서에서는 독자가 필요한 정보를 즉각적으로 찾고 적용할 수 있어야 하기 때문에, 불분명한 표현을 줄이고 직접적이고 구체적인 문장을 작성하는 것이 중요해요.
체크리스트
✅ 명사 대신 동사를 사용하세요
동사는 명사보다 더 직접적이고 간결하게 독자가 무엇을 해야 하는지에 대한 아이디어를 전달합니다. 특히, 동사에서 파생된 명사(예: "설정 수행", "검토 진행")는 의미가 흐릿해지니 되도록 사용하지 않는 게 좋아요.
Don't
코드 최적화 진행 후 배포 수행이 필요합니다.
- '진행', '수행' 같은 불필요한 명사가 포함됐어요.
Do
코드를 최적화한 후 배포하세요
Don't
MongoDB 연결 정보 설정 및 초기화가 필요합니다.
- 의미가 함축된 명사가 많고, 어떤 작업을 해야 하는지 명확하지 않아요.
Do
MongoDB에 연결할 호스트와 포트를 설정하고 데이터베이스를 초기화합니다.
✅ 모호한 표현 대신 명확한 표현을 사용하세요
'가능성이 있다', '일부 경우', '필요할 수도 있다' 같은 모호한 표현을 사용하면 독자가 정확한 의미를 파악하기 어려워져요. 문서의 신뢰도를 위해 확실한 정보를 제공하세요.
Don't
설정 파일을 변경하면 기존 설정이 영향을 받을 수도 있습니다.
일부 브라우저에서 정상적으로 동작하지 않을 가능성이 있습니다.
Do
설정 파일을 변경하면 기존 설정이 삭제됩니다.
Internet Explorer에서는 정상적으로 동작하지 않습니다.
✅ 문장에서 누가, 무엇을, 어디에, 어떻게 하는지 써주세요.
문장에서 누가, 무엇을, 어디에, 어떻게 하는지를 생략하면 문장의 의미가 모호해져요. 독자가 맥락에 의존하지 않고 문장을 이해할 수 있도록 필요한 정보를 모두 넣어주세요.
Don't
파일을 업로드하면 자동으로 저장됩니다.
- 누가 어디에 파일을 저장하는지 알 수 없어요.
Do
사용자가 파일을 업로드하면 서버에 자동으로 저장됩니다.
Don't
설정을 변경하면 적용됩니다.
- 누가 어디에 설정을 적용하는지 알 수 없어요.
Do
관리자가 설정을 변경하면 변경 사항이 프로덕션 환경에 즉시 적용됩니다.
Don't
에러가 발생하면 로그를 확인하세요.
- 에러를 어디에서 확인해야 하는지 알 수 없어요.
Do
에러가 발생하면 애플리케이션 서버에서 에러 로그 파일(/var/log/app/error.log)을 확인하세요.
✅ 실제 동작을 이해할 수 있게 쓰세요
기술 문서를 읽으면 코드나 시스템이 실제로 무엇을 하는지 바로 이해할 수 있어야 해요. 업계에서만 통하는 표현은 실제 동작을 명확하게 설명하지 못해서 문장의 뜻을 흐려요. 독자가 의미를 혼동하지 않도록 문서에서는 실제 동작을 분명하게 드러내는 표현을 사용해 주세요.
Don't
에러가 발생하면 Exception을 던집니다.
- '던져요'는
throw Exception을 그대로 옮긴 표현이라서 개발자도 문맥에 따라 서로 다르게 이해할 수 있어요. 예외를 호출한 쪽에서 처리하도록 전달한다는 뜻인지, 단순히 오류를 반환한다는 뜻인지 상황마다 달라서 오해가 생길 수 있어요.
Do
에러가 발생하면 예외(Exception)를 일으킵니다.
✅ 구체적인 수치나 기준을 제시하세요
'값', '설정', '성능' 같은 단어나 '많을 때', '빠르게' 같은 표현은 문맥에 따라 다르게 해석될 수 있어요. 맥락 없이도 단어가 가리키는 내용을 이해할 수 있게 구체적인 수치와 기준을 사용하세요.
Don't
데이터가 많을 때는 성능이 저하될 수 있습니다.
- '많을 때'가 구체적으로 무엇을 의미하는지, 성능이 얼마나 저하되는지 알 수 없어요.
Do
데이터가 10,000건을 넘으면 응답 시간이 1초 이상 걸립니다.
✅ 참조되는 내용의 맥락을 설명하세요
다른 문서나 단락에서 언급한 변수, 설정값, 개념 등을 다시 사용할 때는, 어디에서 설명했는지 알려주세요. 반대로, 다른 문서나 단락에서 사용할 정보를 처음 언급할 때도 어디에서 사용하는지 알려주세요. 참조되는 부분을 링크를 통해 알려줄 수도 있어요. 독자가 왜 이 정보를 지금 보는지, 나중에 어떻게 사용되는지 이해할 수 있어야 해요.
Don't
- API 키를 생성합니다.
apiKey변수에 저장합니다.
...
apiKey로 API 인증을 수행합니다.
- 1단계에서는
apiKey를 어디에 사용할지 알 수 없어요. 3단계에서는apiKey값을 어디서 얻었는지 확인하기 위해 문서의 앞 부분을 다시 읽어야 해요.
Do
- API 키를 생성하고
apiKey변수에 저장합니다. 이 키는 3단계(3단계 링크)에서 API 키 인증에 사용됩니다.
...
- 1단계(1단계 링크)에서
apiKey에 저장한 API 키로 인증합니다.
실습 문제
아래 문장을 명확하게 수정해보세요. 문제를 풀었다면 답안을 확인해서 비교해 보세요.
1. 명사 대신 동사로 바꿔보세요.
데이터 백업 진행 후 시스템 설정 변경이 필요합니다.
설정 변경 완료 후에는 서비스 재시작 수행이 요구됩니다.
정답 확인
데이터를 백업하고 나서 시스템 설정을 A로 바꿔주세요. 설정을 올바르게 바꾼 뒤에 서비스를 다시 시작해 주세요.
2. 모호한 표현을 명확한 표현으로 바꿔보세요.
일부 환경에서는 소프트웨어 설치 후 정상적으로 실행되지 않을 가능성이 있습니다.
이 경우 추가 구성이 필요할 수도 있습니다.
정답 확인
Windows 7과 같은 구형 운영체제에서는 소프트웨어를 설치해도 실행되지 않을 수 있습니다.
이럴 때는 .NET Framework 4.8을 수동으로 설치해야 합니다.
3. 생략된 정보를 모두 써보세요.
데이터베이스에 연결하면 자동으로 동기화됩니다.
업데이트 시에는 반드시 확인 후 적용해야 합니다.
정답 확인
애플리케이션을 데이터베이스에 연결하면 클라이언트와 서버의 데이터가 자동으로 동기화됩니다.
데이터베이스 스키마를 업데이트할 때는 운영팀이 변경 사항을 확인한 후 프로덕션 환경에 적용해야 합니다.
4. 의미를 명확하게 바꿔보세요.
클라이언트가 서버를 찔러서 응답을 확인합니다. ::: details 정답 확인 클라이언트가 서버에 요청을 보내서 응답을 확인합니다. :::
5. 구체적인 수치나 기준을 제시해보세요.
요청량이 많으면 응답 시간이 느려질 수 있습니다.
파일 크기가 클 때는 업로드에 시간이 걸립니다.
정답 확인
초당 요청량이 1,000건을 넘기면 API 응답 시간이 2초 이상 증가할 수 있습니다.
파일 크기가 100MB를 넘기면 업로드에 최소 30초 이상 걸릴 수 있습니다.
6. 문서 사이에서 참조되는 맥락을 설명해보세요.
- 환경 변수를 설정합니다.
DB_HOST와DB_PORT값을 지정합니다....
- 데이터베이스 연결하기
DB_HOST와DB_PORT를 사용하여 데이터베이스 연결을 시도합니다.
정답 확인
- 환경 변수 설정하기
DB_HOST와DB_PORT값을 지정하세요. 이 값들은 데이터베이스 연결에 사용됩니다....
- 데이터베이스 연결하기 앞서 설정한
DB_HOST와DB_PORT환경 변수를 사용하여 애플리케이션을 데이터베이스에 연결합니다.