Technical Writing One - 기술문서 명확하게 문장 작성하기

테크니컬 라이팅 4원칙에 해당하는 명확성과 연관된 명확하게 문장을 작성하는 방법에 대해서 정리해보고자 합니다. 명확성이란 무엇일까요?

명확성이란 특정 독자가 문서를 읽었을 때 내용의 모호함 없이 한 번에 이해하도록 정보를 제공하는 것이다. 어떤 문장을 읽을 때 내용이 이해가지 않아 몇 번씩 문장을 다시 읽는다는 것은 명확성이 떨어진 문장이다. 

테크니컬 라이터 들은 독자들에게 정보를 명확하게 전달하는 것을 목표로 합니다. 구글에서는 테크니컬 라이팅에서 명확성은 다른 모든 규칙들보다 우선한다.라고 언급하고 있습니다. 

---

Strong verbs 선택하기 

영어로 기술문서를 작성할 때 문장의 가장 중요한 부분은 동사입니다. 하지만 일부 작가는 매일 가벼운 동사만 재사용한다고 합니다. 올바른 동사를 선택하는 것은 많은 시간이 필요하지만 시간을 투자한 만큼 만족스러운 결과를 얻을 수 있습니다.

(원문에서는 strong verb와 weak verb라고 표현했는데 이걸 한글로 번역할 때 강한 동사, 약한 동사라고 표현하는 게 맞는지 모르겠습니다😵)

아래와 같이 부정하거나 약한 일반 동사의 사용을 자제합니다. 

• forms of be: is, are, am, was, were, etc.
• occur
• happen

아래 표처럼 약한 동사를 강한 동사로 변경하면 문장을 더 명확하게 만들어 줍니다. 하지만 아무래도 영어로 되어있다 보니 어떤 느낌인지 확 와닿지는 않는 것 같습니다. 단어의 미묘한 어감 차이는 사전을 보고 공부해봐야겠습니다. 아마  강한 동사들을 사용하면 저처럼 비영어권인 사람들이 해석을 할 때 보다 명확하게 이해할 수 있을 것 같다는 생각이 듭니다. 

약한 동사 vs 강한 동사

아래 제시된 문장에서 다른 동사를 선택하여 문장을 더 명확하게 만들어보겠습니다.

(Before)
When a variable declaration doesn't have a datatype, a compiler error happens.
변수 선언 시 데이터 유형이 없으면 컴파일러 에러가 발생합니다. 

(After)
When a variable declaration doesn't specify a datatype, the complier generates an error message.
변수 선언 시 데이터 유형을 지정하지 않으면 컴파일러는 에러 메시지를 생성합니다. 

기존 문장에서는 have와 happens가 쓰였습니다. 이 동사들은 명확하게 뜻이 전달되지 않으므로 have를 specify, happens를 generates로 바꿔주면 바꾸기 전보다 의미 전달이 잘된다고 합니다. 그래도 코딩을 해본(?) 나는 문장을 처음 봐도 어느 정도 문맥이 이해가 가지만, 경험해보지 않은 사람은 데이터 유형이 없다는 게 무슨 의미지? 내가 지정을 해야 하는 건가? 프로그램이 자동으로 유형을 부여해주는 건가?라고 생각할 수 있을 것 같습니다. 

동사를 바꾸어 작성했을 때 사람이 문맥을 잘 이해할 수 있으면 당연히 컴퓨터도 더 잘 번역할 수 있지 않을까? 라는 생각이 들었고 그래서 저는 구글 번역기를 사용해서 번역을 돌려보았습니다. 위에 작성된 것처럼 '데이터 유형이 없으면'으로 나온 번역 결과가 '데이터 유형을 지정하지 않으면'이라고 번역되는 것을 확인했습니다.

(Before)
Complier errors occur when you leave off a semicolon at the end of a statement.    
명령문의 끝에 세미콜론을 생략하면 컴파일러 오류가 발생합니다. 

(After)
Compliers issue errors when you omit a semicolon at the end of a statement. 
명령문 끝에 세미콜론을 생략하면 컴파일러에서 오류가 발생합니다. 

여기서는 번역 결과가 비슷하게 나오긴 했지만, 개선된 문장을 보면 leave off라는 동사가 문맥상 생략하다는 의미로 쓰여서 자연스럽지만 비영어권인 사람인 제가 봤을 때는 omit가 생략하다 라는 뜻을 더 명확하게 전달한다고 느껴집니다. 또한, Complier issue errors라고 작성해 어디에서 오류가 발생하는지 작성해주었습니다. 

 

There is/There are(~이 있다.) 사용 줄이기 

There is와 There are로 반복되는 문장은 독자를 지루하게 하므로 실제 주어와 동사로 작성하는 것을 권장한다고 합니다. 가장 단순한 방법으로 There is와 There are을 삭제하는 방법이 있습니다. 

(Before)
There is a variable called met_trick that stores the current accuracy.

(After)
There is A variable named met_trick stores the current accuracy.

There is를 제거하고 문장을 작성하면 주어가 명확해지면서 더 좋은 문장이 됩니다. There is를 제거해도 문맥상 전혀 어색하지 않은 것을 확인할 수 있습니다. 

뒤에 있는 주어를 앞으로 가져와서 There is/There are대신 사용할 수 있습니다. 뒤에 있는 you를 앞으로 가지고 오면 아래와 같이 수정할 수 있습니다.

(Before)
There are two disturbing facts about Perl you should know.

(After)
You should know two disturbing facts about Peral.

 

추상적인 언어 사용 최소화하기

기술문서 작성 시 가장 많이 나오는 추상적인 단어를 꼽자면 '정상적으로'라고 생각합니다. 개발자가 작성한 문서에 대해서 제가 실제로 피드백을 제시한 예시입니다.

(Before) Tab에 Load 된 모든 데이터가 정상적으로 저장되는지 확인합니다.
(After)   Tab에 Load 된 모든 데이터가 csv형식으로 저장되는지 확인합니다. 

(Before) 다이얼로그에서 value값 변경 시 정상적으로 Tab에 반영되는지 확인합니다. 
(After)   다이얼로그에서 value값 변경 시 변경된 값이 Tab에 반영되는지 확인합니다.

(Before) 버튼을 클릭하면 저장된 데이터가 레시피에 정상적으로 반영됩니다.
(After)   버튼을 클릭하면 데이터가 레시피에 반영된 후 확인 메시지 창이 나타납니다. 

위와 유사한 패턴을 가진 문장들이 하나의 문서에 반복적으로 등장했습니다. 여기서 꼭 '정상적으로'라는 표현을 써야 될까요? 저는 정상적으로 라는 모호한 표현을 구체적으로 바꿔주었습니다. 추상적인 표현은 기술문서에서 가급적이면 사용하지 않는 것을 권장합니다.  

또 다른 예시로는 기술 마케팅 자료에서 객관적인 수치를 제공하는 것이 좋습니다. 구글에서 제공한 예시를 살펴보면 

(Before)
이 플래그를 설치하면 애플리케이션이 더 빠르게 실행됩니다. 

(After) 
이 플래그를 설치하면 애플리케이션이 225-250% 더 빠르게 실행됩니다. 

기술 문서에서는 '얼마나' 빠르게 실행되는지에 초점을 맞춰서 구체적인 수치로 사실적인 데이터를 제공하는 것을 권장합니다.

 

---

일부 작가는 매일 가벼운 동사만 재사용한다라는 문구가 정곡을 찔렀습니다.😥 회사 방침상 영어로 주간업무 보고서를 작성해야 하는데 항상 똑같은 동사들만 반복했던 내 모습이 떠오르는것 같습니다. 오늘 작성한 내용의 원문은 아래 링크에서 확인할 수 있습니다.

참고 사이트

Clear sentences  |  Technical Writing  |  Google Developers