다이얼로그 컴포넌트의 API 문서를 쓰고 있다. onClose prop에 넘긴 함수는 사용자가 다이얼로그를 닫을 때 컴포넌트가 불러 준다. 문서를 읽는 사람에게 중요한 것은 이 함수가 언제 불리는지다. 누가 부르는지(컴포넌트 내부)는 몰라도 된다.
| 용어 | 뜻 |
|---|---|
| 주어(subject) / 목적어(object) | 주어는 동작을 하는 쪽(누가·무엇이), 목적어는 동작을 받는 대상(누구를·무엇을)이다. 예문의 주어는 The CLI, 목적어는 the config file이다. 예: The CLI reads the config file. |
| 과거분사(past participle) | 동사의 한 꼴. 규칙 동사는 -ed를 붙이고(fixed), 불규칙 동사는 따로 익힌다(found, written). 예: I've fixed the flaky test. |
| 행위자(agent) | 그 동작을 실제로 하는 사람이나 사물. 예문에서는 The scheduler다. 예: The scheduler runs the job every hour. |
| 능동태(active voice) | 행위자를 주어로 세운 문장 형태. 예: The bot merged the PR. |
| 수동태(passive voice) | 동작을 받는 대상을 주어로 세운 문장 형태. 예: The PR was merged. |
API 문서의 prop 설명: onClose ___ when the user closes the dialog. 빈칸에 알맞은 것은?
규칙: be + 과거분사, 행위자가 중요하지 않을 때
A. 수동태는 be + 과거분사(past participle)로 만든다. 능동태(active voice) 문장의 목적어를 주어로 세운다(British Council: Passives). 시제(tense)는 be가 맡고, 과거분사는 그대로 둔다.
The config file was not found.(과거)This method is deprecated.(현재)The PR has been merged.(현재완료. Unit 2에서 본 present perfect 형태)This option will be removed in v4.(미래)
B. 행위자를 모르거나 중요하지 않으면 수동태를 쓴다. 같은 문서가 누가 했는지 말하지 않는 편이 나을 때 수동태를 쓴다고 설명한다. Google 개발자 문서 스타일 가이드도 행위보다 대상을 강조할 때, 누가 했는지 독자가 알 필요가 없을 때는 수동태를 써도 된다고 한다(Google 개발자 문서 스타일 가이드: Active voice).
onError is called when the request fails.The request was rejected because the token had expired.This endpoint is rate-limited to 100 requests per minute.
C. 행위자가 중요하면 능동태가 기본이다. 같은 가이드는 일반적으로 능동태를 쓰고, 행위자를 문장의 주어로 세우라고 권한다. 수동태로 쓰면 누가 하는지를 빠뜨리기 쉬워서다. 문서에서 독자가 해야 할 일이나 시스템이 하는 일을 설명할 때는 행위자를 주어로 쓴다.
The CLI reads the config file from the project root.(The config file is read from the project root.보다 누가 읽는지 분명하다)Run the migration before you deploy.
D. 에러 메시지는 be를 빼고 줄여 쓰기도 한다. File not found, Access denied, Connection refused는 The file was not found에서 관사(article)와 be 동사를 뺀 꼴로 읽으면 된다. HTTP 상태 문구 404 Not Found도 같은 꼴로 읽힌다(RFC 9110). 형태는 여전히 과거분사라서 File not finding처럼 바꿀 수 없다. 문장으로 쓸지 줄여 쓸지는 한 제품 안에서 하나로 맞추는 편이 읽기 쉽다.
표현: 문서와 메시지에 쓰는 수동태
| 표현 | 언제 | 예 |
|---|---|---|
X is deprecated | 지원 중단을 알릴 때 | This option is deprecated. Use --output instead. |
X will be removed in … | 제거 시점을 예고할 때 | The v1 endpoints will be removed in March. |
X is called when … | 콜백·훅이 불리는 때를 설명할 때 | onSubmit is called when the form is valid. |
X is required | 필수 값이 빠졌을 때 | The --token flag is required. |
X was not found / X not found | 찾는 대상이 없을 때 | No tests were found in src/. |
X has been … | 처리된 상태를 알릴 때 | Your changes have been saved. |
장애 보고에서는 수동태를 쓸 곳과 피할 곳이 갈린다. 원인과 영향은 Requests to the payment API were dropped for 12 minutes.처럼 대상을 주어로 써도 된다. 하지만 조치 항목을 The deploy was rolled back.(roll back: 이전 버전으로 되돌리다)으로만 쓰면 누가 판단하고 실행했는지가 사라진다. 개인을 탓하지 않는 보고서라도 팀이 한 조치는 At 14:10, we rolled back the deploy.처럼 we를 주어로 쓰면 누가 했는지가 남는다. we는 팀 전체라서 개인을 지목하지 않고도 행위자를 밝힐 수 있다.
The file was not found.An error was occurred라고 쓰기 쉽습니다. occur, happen처럼 목적어를 받지 않는 동사는 수동태가 없습니다. An error occurred.로 씁니다. '파일을 찾을 수 없습니다'의 '파일'을 주어로 세우고 동사는 능동태로 두면 The file did not find.처럼 파일이 찾는 주체가 됩니다.함정 찾기: AI가 쓴 CLI 메시지
CLI의 에러·경고·안내 메시지를 영어로 써 줘.
- 설정 파일 없음
- 토큰 필수
- --out 옵션 지원 중단
- 파싱 중 알 수 없는 에러
- 저장 완료
의심스러운 줄을 모두 눌러 표시한 뒤 “검토 끝”을 누르세요. 함정은 2개입니다.
연습
1. 지원 중단 안내:
"This hook ___ deprecated. Use useQuery instead."
2. "이 버그는 지난주 배포 이후 발생했다"를 영어로 옮길 때 문법이 맞는 것은?
3. 장애 보고서의 조치 항목. 우리 팀이 직접 한 조치임을 분명히 쓰려면?
4. "사용자를 찾을 수 없음"을 줄인 에러 메시지로 쓸 때는?