지난 Part에서는 테크니컬 라이팅의 개념과 글쓰기 작성 프로세스에 대해 알아보았습니다. 일반 글쓰기의 경우 형식과 표현의 제한 없이, 정해진 원칙이나 규칙과 상관없이 자유롭게 쓸 수 있지만 테크니컬 라이팅은 주의해야 할 몇 가지 원칙이 있습니다. 오늘은 테크니컬 라이팅의 네 가지 원칙에 대해 알아보겠습니다.
1. 정확성
정확한 글이란 독자가 필요로 하는 정보를 기술적 오류 없이 정확하게 제공하는 글을 말합니다. 비록 명확하지 않고 간결하지 않은 글이더라도 정확한 글이라면 독자들은 끝까지 해당 문서를 읽고 이해할 수 있습니다. 하지만 잘못된 정보를 포함한 기술 문서는 내용을 이해한다고 해도 결국 잘못된 정보를 제공했기 때문에 필요 없는 문서가 됩니다. 따라서 기술 문서를 작성할 때에는 특히 정확도에 주의해야 합니다. 최신 정보와 검증 가능한 정보를 통해 정확하고 사실인 내용을 적어야 하고, 신뢰할 수 있는 출처를 사용하며 가정이나 일반화는 피해야 합니다.
정확성 있는 문서를 작성하기 위해서는 주제에 대해 충분히 이해하고 있어야 합니다. 초안 작성을 끝낸 뒤에는 여러 사람들과의 리뷰를 통해 정확성을 높일 수 있고 자주 변경되는 내용은 버전 관리도 신경 써야 합니다. 특이 자주 발생하는 내용 상의 오류는 UI 화면에 표시된 버튼과 문서에 설명된 버튼 이름이 다르거나 업데이트 내용이 반영되지 않는 등 입니다. 정확성을 높이기 위해서는 문서 초안 작성을 한 뒤 내용을 검증해 보는 과정이 가장 중요합니다.
정확한 글을 쓰기 위해 주의할 할 요소
(1) 정확한 단위 사용
정확한 단위를 사용하여 작업에 오류가 없도록 합니다.
| 수정 전 | 수정 후 |
| 가로 1080 * 세로 630 | 가로 1080px 세로 630px |
(2) 수치 등 정학 내용 기입
최소 값, 최대 값 등 정확한 내용을 기입합니다.
| 수정 전 | 수정 후 |
| 비밀번호는 최소 6자까지 설정해야 합니다. | 비밀번호는 6자 이상 10자 이하로 설정해야 합니다. |
2. 명확성
명확한 글이란 핵심어 혹은 핵심 문장이 모호하게 사용되지 않고 독자들이 문서를 읽을 때 혼란 없이 한 번에 이해할 수 있는 글을 말합니다. 만약 어떠한 문서 혹은 문장을 읽을 때 이해가 되지 않아 몇 번 씩 다시 읽게 된다면 명확성이 떨어지는 글입니다.
명확성이 모호해지는 이유는 독자를 제대로 파악하지 못했기 때문입니다. 이와 관련해서는 '이 내용은 관련 분야 사람이라면 당연히 다 아는 내용인데 설명해야 하나요?'와 같은 질문을 할 수 있습니다. 결론적으로는 다 아는 내용이라도 설명해야 합니다. '관련 분야 사람이라면 당연히 다 아는 내용'이라는 생각은 주관적일 수 있고 실제로 독자가 개발자 혹은 엔지니어라고 해도 경력이나 실력에 따라서 초급/중급/시니어 개발자로 나뉘기도 하며 기술 문서는 내부에서만 공유되는 것이 아니라 외부에도 공유될 수 있기 때문입니다. 따라서 대학생, 외부의 초급 레벨 관련자들도 쉽게 읽고 따라 할 수 있는 정도의 상세한 문서여야 합니다.
명확한 글을 쓰기 위해 주의할 요소
(1) 약어와 줄임말 지양
약어와 줄임말을 지양하되, 널리 쓰이고 있는 말이라면 그 뜻을 짧게 풀이해줄 수 있는 각주와 같은 기능을 활용합니다.
| 수정 전 | 수정 후 |
| 일반적인 해킹 방법으로 BEC가 6%로 3위를 차지했습니다. | 일반적인 해킹 방법으로 BEC*가 6%로 3위를 차지했습니다. *BEC : 기업 이메일 침해(business email compromise, BEC) |
(2) 능동태와 수동태의 적절한 사용
사용자가 수행해야 하는 동작을 설명하는 것이라면 명확하게 표현해야 합니다.
| 수정 전 | 수정 후 |
| 확인 버튼을 클릭하면 내용을 삭제합니다. | 확인 버튼을 클릭하면 내용이 삭제됩니다. |
(3) 이중 부정 지양
이중 부정은 한 문장에서 부정소가 두 번 사용되어 내용적으로 긍정이 되는 부정법으로, 명확성을 떨어뜨리기 때문에 지양해야 합니다.
| 수정 전 | 수정 후 |
| 작성한 글을 두 번씩 확인하지 않으면 안됩니다. | 작성한 글을 두 번씩 확인해야 합니다. |
(4) 문맥에 맞는 조사 사용
조사는 어떻게 쓰느냐에 따라 단순히 어감이 달라지는 것이 아닌 문법적으로 잘못된 문장이 되기 때문에 주의해야 합니다.
| 수정 전 | 수정 후 |
| 업무할 때 선택할 수 있는 협업 툴이 줄어든 반면에, 비용은 크게 늘었습니다. |
업무할 때 선택할 수 있는 협업 툴은 줄어든 반면에, 비용은 크게 늘었습니다. |
(5) 중복 높임 지양
올바른 높임법을 사용해야 합니다.
| 수정 전 | 수정 후 |
| 첨부된 문서를 확인하시고 사용하세요. | 첨부된 문서를 확인 후 사용하세요. |
3. 간결성
간결한 글이란 독자가 정보를 빠르게 이해할 수 있도록 감탄사, 미사여구 등을 사용하지 않고 쉽고 간결하며 쉬운 단어를 사용한 글을 말합니다. 기술 문서라고 하여 길고 복잡하게, 전문 용어를 과도하게 사용하여 복문으로 작성하는 것은 바람직하지 않습니다. 짧고 간결한 문장을 사용할수록 명확하고 가독성 높은 글을 작성할 수 있고 독자는 글을 더욱 이해하기 쉬워집니다.
간결한 글을 쓰기 위해 주의할 요소
(1) 불필요한 부사 사용 지양
불필요한 부사의 사용을 지양하면 글이 간결해집니다.
| 수정 전 | 수정 후 |
| ① 재부팅으로 해결하는 것이 가장 좋습니다. ② 성공적으로 로그인 했습니다. |
① 재부팅으로 해결하는 것이 좋습니다. ② 로그인 했습니다. |
(2) 불필요한 수식서 사용 지양
불필요한 수식어의 사용을 지양하면 글이 간결해집니다.
| 수정 전 | 수정 후 |
| 소요되는 시간이 상당히 많습니다. | 시간이 많이 듭니다. |
(3) 긍정적 표현 지향
부정적 표현을 사용할 경우 글이 불필요하게 길어지고 의미 해석에 오류가 생길 수 있으므로 명확하고 간결한 문장을 위해 긍정적 표현을 사용하도록 합니다.
| 수정 전 | 수정 후 |
| 오류 문구는 포함해 전송하지 않습니다. | 오류 문구는 제외 후 전송됩니다. |
(4) 중복 표현 사용 지양
중복 표현은 반복형 강조법처럼 여겨질 수 있지만 문장의 간결성을 떨어뜨립니다.
| 수정 전 | 수정 후 |
| 연휴가 계속되어 회신이 늦었습니다. | 연휴가 되어 회신이 늦었습니다. |
| *연휴(連休)의 '련(連)'자는 '잇닿다, 연속하다'를 뜻해 '연휴'는 '계속되다'라는 뜻을 포함 | |
4. 일관성
일관성 있는 글이란 독자가 문서를 읽을 때 쉽게 이해할 수 있도록 용어와 표현 그리고 어조 등을 일관성 있게 사용한 글입니다. 일반 글쓰기의 경우 다양한 표현을 사용하며 독자에게 즐거움을 줄 수 있지만, 기술 문서를 작성할 때에는 글의 해석과 관련된 오해를 남기면 안 되기 때문에 일관성을 유지해야 합니다. 문서의 제목과 본문의 폰트 크기 등도 통일한다면 가독성이 높아지고 문서 전체의 일관성이 높아집니다.
일관된 글을 쓰기 위해 주의할 요소
(1) 일관된 명칭
여러 가지 명칭을 혼용하는 것이 아닌, 한 가지 명칭을 정해 통일성 있게 작성해야 합니다.
| 수정 전 | 수정 후 |
| OpenMSP, OSC Managed Service, 오에스씨 컨설팅 서비스 | OpenMSP™ |
(2) 일관된 표현
일관된 표현을 사용해 문서 전체의 일관성을 높이는 것이 좋습니다.
| 수정 전 | 수정 후 |
| 일간 보고서에는 정확한 날짜를 기입합니다. 일간 보고서에는 정확한 날짜를 입력합니다. |
일간 보고서에는 정확한 날짜를 기입합니다. |
테크니컬 라이팅을 할 때에는 청중이 누구인지, 어떤 목적으로 쓰는 글인지 간과하지 않도록 주의하고 위 4가지의 원칙을 유념해 글을 작성한다면 독자를 위한 글을 쓰는 데에 큰 도움이 될 것 입니다.
참고
유시민 『유시민의 글쓰기 특강』
