개발을 하다 보면 영어 문서를 읽어야 하는 경우가 많다.
프로그래밍 언어 공식 문서, 라이브러리 API, GitHub README, RFC, 에러 메시지, SDK 문서 등이 대표적이다.
기술 문서를 읽을 때 영어 문장을 하나씩 한국어로 번역하려고 하면 오히려 느려진다.
중요한 것은 문장의 구조를 보고 무엇을 하는지, 어떤 조건이 필요한지, 무엇을 반환하는지, 어떤 경우에 실패하는지를 파악하는 것이다.
기술 문서의 기본 구조
대부분의 기술 문서는 다음 정보를 중심으로 구성된다.
Purpose -> Usage -> Parameters -> Behavior -> Return Value -> Exceptions -> Example
각 항목의 의미는 다음과 같다.
Purpose
-> 무엇을 위한 기능인가
Usage
-> 어떻게 사용하는가
Parameters
-> 무엇을 입력하는가
Behavior
-> 어떻게 동작하는가
Return Value
-> 무엇을 반환하는가
Exceptions
-> 어떤 경우에 실패하는가
Example
-> 실제 사용 방법은 무엇인가
문서를 읽을 때 이 구조를 먼저 찾으면 긴 문서도 빠르게 파악할 수 있다.
가장 중요한 동사
기술 문서에서 반복해서 등장하는 동사는 따로 익혀두는 것이 좋다.
create
-> 생성하다
initialize
-> 초기화하다
configure
-> 설정하다
define
-> 정의하다
declare
-> 선언하다
implement
-> 구현하다
invoke
-> 호출하다
execute
-> 실행하다
return
-> 반환하다
retrieve
-> 가져오다
fetch
-> 가져오다
update
-> 갱신하다
modify
-> 수정하다
remove
-> 제거하다
delete
-> 삭제하다
handle
-> 처리하다
validate
-> 검증하다
parse
-> 파싱하다
convert
-> 변환하다
serialize
-> 직렬화하다
deserialize
-> 역직렬화하다
allocate
-> 할당하다
release
-> 해제하다
resolve
-> 해결하다
reject
-> 거부하다
prevent
-> 방지하다
allow
-> 허용하다
require
-> 요구하다
support
-> 지원하다
depend
-> 의존하다
inherit
-> 상속하다
override
-> 재정의하다
expose
-> 노출하다
consume
-> 소비하다
generate
-> 생성하다
process
-> 처리하다
기술 문서에서 자주 나오는 명사
코드
variable
-> 변수
constant
-> 상수
parameter
-> 매개변수
argument
-> 인자
property
-> 속성
field
-> 필드
method
-> 메서드
function
-> 함수
class
-> 클래스
interface
-> 인터페이스
instance
-> 인스턴스
implementation
-> 구현
dependency
-> 의존성
reference
-> 참조
데이터
value
-> 값
input
-> 입력
output
-> 출력
result
-> 결과
request
-> 요청
response
-> 응답
payload
-> 전달 데이터
resource
-> 리소스
metadata
-> 메타데이터
configuration
-> 설정
state
-> 상태
context
-> 문맥 / 실행 환경
동작
behavior
-> 동작
operation
-> 작업 / 연산
process
-> 처리
workflow
-> 작업 흐름
lifecycle
-> 생명주기
condition
-> 조건
requirement
-> 요구사항
constraint
-> 제약 조건
restriction
-> 제한
permission
-> 권한
문서에서 가장 중요한 조동사
기술 문서에서는 must, should, may, can의 차이를 정확하게 봐야 한다.
must
The value must not be null.
값은 null이어서는 안 된다.
강제 조건이다.
must
-> 반드시
-> 필수
-> 위반하면 안 됨
should
The method should return a valid result.
메서드는 유효한 결과를 반환해야 한다.
일반적으로 권장사항이나 기대되는 동작이다.
should
-> ~해야 한다
-> 권장된다
must보다 강도가 낮다.
may
This operation may fail.
이 작업은 실패할 수 있다.
가능성을 나타낸다.
may
-> ~할 수 있다
-> 가능성이 있다
can
This method can be called multiple times.
이 메서드는 여러 번 호출할 수 있다.
가능하거나 허용되는 동작을 나타낸다.
can
-> ~할 수 있다
조건 표현
기술 문서를 읽을 때 조건 표현을 빠르게 찾는 것이 중요하다.
if
If the value is null, an exception is thrown.
값이 null이면 예외가 발생한다.
if A -> B
unless
The cache is used unless it has expired.
캐시가 만료되지 않았다면 캐시를 사용한다.
A unless B
-> B가 아니라면 A
when
The event is triggered when the object is destroyed.
객체가 파괴될 때 이벤트가 발생한다.
when A -> B
before / after
Call this method before initialization.
초기화 전에 이 메서드를 호출한다.
Call this method after initialization.
초기화 후에 이 메서드를 호출한다.
before
-> 이전에
after
-> 이후에
while
The process continues while the connection is active.
연결이 활성화되어 있는 동안 프로세스가 계속된다.
while A -> B
otherwise
Return the cached value. Otherwise, fetch the data.
캐시 값을 반환한다. 그렇지 않으면 데이터를 가져온다.
조건 만족 -> A
otherwise -> B
제한을 나타내는 표현
기술 문서에서는 “할 수 있다”보다 “할 수 없는 조건”을 확인하는 것이 더 중요할 때가 많다.
must not
-> ~해서는 안 된다
cannot
-> ~할 수 없다
not supported
-> 지원되지 않는다
not allowed
-> 허용되지 않는다
restricted to
-> ~로 제한된다
only
-> 오직 ~만
except
-> ~을 제외하고
requires
-> ~을 요구한다
depends on
-> ~에 의존한다
예:
This operation is only supported on Windows.
핵심:
Windows에서만 지원
API 문서 읽기
API 문서는 보통 다음 정보를 제공한다.
Name
-> Parameters
-> Return Value
-> Exceptions
-> Remarks
-> Example
예:
GetComponent<T>()
Retrieves the component of the specified type
from the GameObject.
Parameters:
T
The type of component to retrieve.
Returns:
The component if found; otherwise, null.
전체를 번역하기보다 다음처럼 읽는다.
GetComponent<T>
-> 특정 타입의 Component 검색
Input
-> T
Success
-> Component
Failure
-> null
이 정도면 실제 사용에 필요한 핵심 정보를 얻을 수 있다.
Parameters 읽기
Parameter 설명에서는 타입, 필수 여부, 기본값, 허용 범위를 확인한다.
count
The number of items to retrieve.
Must be greater than zero.
다음처럼 정리한다.
count
-> 가져올 항목 수
-> 0보다 커야 함
다음과 같은 표현도 자주 나온다.
required
-> 필수
optional
-> 선택 사항
default
-> 기본값
minimum
-> 최솟값
maximum
-> 최댓값
range
-> 범위
valid
-> 유효한
invalid
-> 유효하지 않은
Return Value 읽기
반환값은 반드시 확인해야 한다.
Returns the requested object.
Returns null if the object does not exist.
핵심:
성공 -> object
실패 -> null
다음과 같은 표현도 자주 등장한다.
Returns true if successful.
-> 성공하면 true 반환
Returns false if the operation fails.
-> 실패하면 false 반환
Returns an empty collection if no items are found.
-> 항목이 없으면 빈 컬렉션 반환
Returns null when the value is unavailable.
-> 값을 사용할 수 없으면 null 반환
Exception 읽기
예외 설명에서는 어떤 조건에서 발생하는지가 핵심이다.
Throws ArgumentNullException if input is null.
input == null -> ArgumentNullException
자주 등장하는 표현:
throws
-> 예외를 발생시킨다
raises
-> 예외를 발생시킨다
fails
-> 실패한다
fails when
-> ~할 때 실패한다
occurs when
-> ~할 때 발생한다
in case of
-> ~의 경우
if
-> ~이면
상태 표현
기술 문서는 상태를 나타내는 표현이 매우 많다.
enabled
-> 활성화됨
disabled
-> 비활성화됨
active
-> 활성 상태
inactive
-> 비활성 상태
available
-> 사용 가능
unavailable
-> 사용 불가
connected
-> 연결됨
disconnected
-> 연결 끊김
initialized
-> 초기화됨
uninitialized
-> 초기화되지 않음
valid
-> 유효함
invalid
-> 유효하지 않음
pending
-> 처리 대기 중
completed
-> 완료됨
failed
-> 실패함
시간과 순서 표현
before
-> 이전
after
-> 이후
during
-> ~하는 동안
while
-> ~하는 동안
until
-> ~할 때까지
immediately
-> 즉시
automatically
-> 자동으로
synchronously
-> 동기적으로
asynchronously
-> 비동기적으로
eventually
-> 결국 / 최종적으로
initially
-> 처음에는
currently
-> 현재
previously
-> 이전에
예:
The callback is invoked asynchronously after the operation completes.
핵심:
operation 완료
-> 비동기적으로 callback 호출
비교 표현
성능이나 설계 문서에서 자주 등장한다.
faster
-> 더 빠른
slower
-> 더 느린
larger
-> 더 큰
smaller
-> 더 작은
higher
-> 더 높은
lower
-> 더 낮은
more efficient
-> 더 효율적인
less efficient
-> 덜 효율적인
better
-> 더 나은
worse
-> 더 나쁜
예:
This approach is more efficient than the previous implementation.
핵심:
현재 방식 > 이전 구현
-> 효율이 더 좋음
성능 관련 표현
게임 개발에서는 특히 자주 접하게 된다.
performance
-> 성능
optimization
-> 최적화
bottleneck
-> 병목
overhead
-> 추가 비용
latency
-> 지연 시간
throughput
-> 처리량
memory usage
-> 메모리 사용량
allocation
-> 할당
deallocation
-> 할당 해제
frame time
-> 프레임 처리 시간
CPU usage
-> CPU 사용량
GPU usage
-> GPU 사용량
memory footprint
-> 메모리 사용량 / 메모리 점유량
예:
This operation introduces significant overhead.
operation
-> 추가 비용이 큼
Avoid unnecessary allocations in the update loop.
update loop에서 불필요한 할당을 피하라.
동시성 관련 표현
thread
-> 스레드
concurrent
-> 동시적인
parallel
-> 병렬적인
synchronize
-> 동기화하다
lock
-> 잠금
race condition
-> 경쟁 상태
deadlock
-> 교착 상태
thread-safe
-> 스레드 안전
atomic
-> 원자적
shared state
-> 공유 상태
access
-> 접근
예:
This method is not thread-safe.
핵심:
여러 스레드에서 안전하게 사용할 수 없음
네트워크 문서 표현
request
-> 요청
response
-> 응답
connection
-> 연결
disconnect
-> 연결 해제
packet
-> 패킷
protocol
-> 프로토콜
timeout
-> 시간 초과
retry
-> 재시도
reliable
-> 신뢰성이 보장되는
unreliable
-> 신뢰성이 보장되지 않는
serialize
-> 직렬화
deserialize
-> 역직렬화
synchronize
-> 동기화
replicate
-> 복제
authenticate
-> 인증
authorize
-> 권한 확인
게임 네트워크에서는 다음 표현도 자주 나온다.
client prediction
-> 클라이언트 예측
server reconciliation
-> 서버 기준 상태 보정
lag compensation
-> 지연 보상
state synchronization
-> 상태 동기화
authoritative server
-> 서버 권위 구조
GitHub README 읽기
README는 일반적인 기술 문서보다 구조가 단순하다.
Overview
-> 무엇인가
Installation
-> 어떻게 설치하는가
Requirements
-> 무엇이 필요한가
Usage
-> 어떻게 사용하는가
Configuration
-> 어떻게 설정하는가
Examples
-> 어떻게 사용하는가
Limitations
-> 어떤 제한이 있는가
Known Issues
-> 알려진 문제
Contributing
-> 어떻게 기여하는가
License
-> 어떤 라이선스인가
특히 Requirements, Limitations, Known Issues는 놓치면 안 된다.
설치가 되는 것과 제대로 사용할 수 있는 것은 별개의 문제이기 때문이다.
기술 문장에서 핵심 정보 추출하기
다음 문장을 보자.
The cache is automatically invalidated when the specified
timeout expires, and subsequent requests will fetch fresh data.
처음부터 끝까지 번역할 필요가 없다.
핵심 구조:
timeout expires
-> cache invalidated
-> subsequent request
-> fetch fresh data
결국:
timeout 만료 -> 캐시 무효화 -> 다음 요청 -> 새로운 데이터 가져오기
기술 문서는 이런 식으로 동작 흐름으로 변환해서 읽는 것이 효율적이다.
수동태에 익숙해지기
기술 문서에는 수동태가 매우 자주 나온다.
The object is created automatically.
객체가 자동으로 생성된다.
The value is stored in memory.
값이 메모리에 저장된다.
The method is called when the event occurs.
이벤트가 발생하면 메서드가 호출된다.
중요한 것은 수동태 자체가 아니다.
다음 구조를 찾으면 된다.
무엇이 -> 어떻게 처리되는가
긴 문장 끊어 읽기
기술 문장이 길어도 핵심 구조는 단순한 경우가 많다.
The method returns a cached result if available,
otherwise it performs a network request to retrieve
the latest data from the server.
다음처럼 끊는다.
method
-> returns cached result
-> if available
otherwise
-> network request
-> retrieve latest data
한국어로 완벽하게 번역하기보다 조건과 동작을 분리해서 읽는다.
관계를 나타내는 표현
based on
-> ~을 기반으로
depending on
-> ~에 따라
according to
-> ~에 따르면
related to
-> ~와 관련된
associated with
-> ~와 연관된
consists of
-> ~로 구성된다
consists in
-> ~에 있다
refers to
-> ~을 가리킨다
used for
-> ~에 사용된다
responsible for
-> ~을 담당한다
compatible with
-> ~와 호환된다
incompatible with
-> ~와 호환되지 않는다
의존성을 나타내는 표현
depends on
-> ~에 의존한다
requires
-> ~을 요구한다
requires at least
-> 최소 ~이 필요하다
requires a valid
-> 유효한 ~이 필요하다
is based on
-> ~을 기반으로 한다
is provided by
-> ~에 의해 제공된다
is derived from
-> ~에서 파생된다
예:
This feature requires Unity 6 or later.
Unity 6 이상 필요
권장사항 읽기
문서에서는 직접적인 명령보다 권장사항 형태가 많이 나온다.
We recommend using ...
-> ~사용을 권장한다
It is recommended that ...
-> ~하는 것이 권장된다
You should ...
-> ~하는 것이 좋다
Avoid ...
-> ~을 피하라
Do not ...
-> ~하지 마라
Prefer ...
-> ~을 선호하라
Consider ...
-> ~을 고려하라
예:
Avoid creating objects inside the Update method.
핵심:
Update에서 객체 생성하지 말 것
Deprecated 읽기
개발 문서에서 매우 중요한 단어다.
deprecated
-> 더 이상 사용을 권장하지 않는
예:
This method is deprecated.
단순히 “삭제되었다”는 뜻이 아니다.
현재 사용할 수 있을 수도 있지만 새로운 코드에서는 사용하지 않는 것이 권장된다는 의미다.
함께 확인해야 하는 표현:
deprecated
-> 사용 중단 권고
obsolete
-> 더 이상 사용되지 않는
removed
-> 제거됨
replaced by
-> ~로 대체됨
use instead
-> 대신 ~을 사용하라
버전 관련 표현
introduced in
-> ~버전에서 추가됨
available since
-> ~부터 사용 가능
deprecated since
-> ~부터 deprecated
removed in
-> ~버전에서 제거됨
supported from
-> ~부터 지원
requires
-> 최소 요구 버전
latest
-> 최신
stable
-> 안정 버전
preview
-> 미리보기
experimental
-> 실험적
예:
This API was introduced in version 2.0.
2.0에서 추가된 API
오류와 문제 관련 표현
error
-> 오류
exception
-> 예외
failure
-> 실패
bug
-> 버그
issue
-> 문제
crash
-> 충돌
invalid
-> 잘못된 / 유효하지 않은
missing
-> 누락된
unexpected
-> 예상하지 못한
unsupported
-> 지원되지 않는
conflict
-> 충돌
corrupted
-> 손상된
문서에서 다음 표현도 자주 나온다.
fails when
-> ~할 때 실패
causes
-> ~을 발생시킨다
results in
-> 결과적으로 ~이 발생한다
leads to
-> ~을 초래한다
may cause
-> ~을 발생시킬 수 있다
prevents
-> ~을 방지한다
RFC와 기술 사양 읽기
RFC나 Specification은 일반 API 문서보다 형식이 딱딱하다.
자주 나오는 표현:
MUST
-> 반드시 해야 함
MUST NOT
-> 절대 해서는 안 됨
SHOULD
-> 권장
SHOULD NOT
-> 권장하지 않음
MAY
-> 해도 됨 / 가능함
OPTIONAL
-> 선택 사항
REQUIRED
-> 필수
IMPLEMENTATION
-> 구현
COMPATIBILITY
-> 호환성
COMPLIANCE
-> 준수
특히 대문자로 쓰인 MUST, SHOULD, MAY는 일반적인 영어보다 강한 기술적 의미를 가지는 경우가 많다.
기술 문서를 읽는 순서
처음부터 끝까지 읽는 방식은 비효율적이다.
다음 순서가 좋다.
제목
-> Overview
-> Requirements
-> Usage
-> Parameters
-> Return Value
-> Exceptions
-> Limitations
-> Example
문제 해결 목적이라면 더 짧게 읽을 수 있다.
문제
-> 검색
-> 관련 API
-> Parameters
-> Return Value
-> Exceptions
-> Example
모르는 단어가 나왔을 때
모든 단어를 찾아볼 필요는 없다.
먼저 문맥으로 의미를 추측한다.
문장 전체
-> 핵심 동사
-> 대상
-> 조건
-> 결과
그리고 동작을 이해하는 데 필요한 단어만 검색한다.
예를 들어:
The method invalidates the cached value when the
underlying resource changes.
underlying을 정확하게 몰라도 전체 동작은 파악할 수 있다.
resource changes
-> cached value invalidated
이 정도면 충분하다.
반대로 invalidate를 모른다면 반드시 확인하는 것이 좋다.
invalidate
-> 유효하지 않게 만들다
기술 영어에서 우선적으로 외워야 하는 것
우선순위를 잡으면 다음과 같다.
동사
-> 조건 표현
-> 조동사
-> API 용어
-> 오류 표현
-> 상태 표현
-> 성능 표현
-> 버전 표현
특히 다음 표현은 바로 이해할 수 있는 수준까지 익히는 것이 좋다.
must
should
may
can
if
unless
otherwise
when
before
after
until
require
support
provide
return
throw
handle
create
initialize
configure
implement
invoke
retrieve
fetch
validate
parse
serialize
deserialize
deprecated
obsolete
unsupported
compatible
available
required
optional
핵심은 번역이 아니다
기술 문서를 읽는 목적은 영어 공부가 아니다.
문서가 정의한 규칙을 정확하게 파악하는 것이다.
따라서 다음 질문에 답할 수 있으면 된다.
무엇인가?
-> 무엇을 하는가?
-> 무엇을 입력받는가?
-> 무엇을 반환하는가?
-> 어떤 조건이 필요한가?
-> 어떤 경우에 실패하는가?
-> 어떤 제한이 있는가?
-> 어떤 버전에서 사용할 수 있는가?
기술 문장을 코드의 흐름으로 바꾸면 더 쉽게 이해할 수 있다.
문서
-> 조건
-> 동작
-> 결과
-> 예외
예를 들어:
If the connection is lost,
the client retries the request up to three times.
문장을 해석하는 것보다:
connection lost
-> retry request
-> maximum 3 times
이렇게 보는 것이 개발자에게 더 직접적이다.
최종 정리
기술 문서 영어에서 가장 중요한 것은 어휘량 자체가 아니다.
단어 인식
-> 문장 구조 파악
-> 조건 추출
-> 동작 추출
-> 결과 추출
-> 제약 조건 확인
그리고 기술 문서는 일반 영어와 다르게 정확한 의미의 차이가 중요하다.
must != should
may != can
remove != deprecate
error != exception
create != initialize
parameter != argument
compile != build
available != supported
이 차이를 이해하면 공식 문서, API Reference, GitHub README, RFC, SDK 문서를 읽는 속도가 크게 달라진다.
결국 기술 영어의 목표는 영어를 한국어로 완벽하게 번역하는 것이 아니다.
영어 문서
-> 기술적 의미 추출
-> 코드 / 구조 / 동작으로 변환
-> 실제 개발에 적용
개발자는 영어를 읽는 사람이 아니라, 영어로 작성된 기술 정보를 해석하는 사람이다.