기술 문서는 제품 개발, 사용을 위한 모든 문서와 자료입니다. 이는 제품 사용법, 기능, 아키텍처를 설명하죠. 혹자는 '이메일을 비롯해 회사에서 작성하는 모든 문서'를 기술 문서로 보기도 합니다. 기술 문서는 사용자에게 기술 정보를 틀림 없이, 이해하기 쉽게 전달해야 합니다. 사용자는 기술 문서에서 필요한 정보를 빠르고 쉽게 얻을 수 있어야 합 니다. 이 글은 정확하고, 잘 읽히며, 유용한 기술 문서를 쓰기 위해 고려할 사항을 담았습니다.
*이 글은 테크니컬 라이팅 일반 원칙, 문장 원칙을 주로 다뤘습니다. 글 내용은 앞으로 상황과 필요에 따라 추가, 수정될 수 있습니다.
*이 글은 할 일 목록(To-Do List) 형태로 작성했습니다. 각 항목을 체크하며 글을 점검하길 권장합니다.
*이 글은 인포그랩 내부 스타일 가이드로, 8번 (GitLab 관련) 영문 표기는 타사에 일괄로 적용하기에 맞지 않을 수 있습니다.
*이 글은 테크니컬 라이팅·웹 글쓰기·우리말 관련 도서, 마이크로소프트·구글·GitLab 스타일 가이드, 카카오 엔터프라이즈·NHN 클라우드·토스의 테크니컬 라이팅 콘텐츠 등을 참고해 작성했습니다. 각 참고 자료에서 공통으로 다룬 내용, 실무에 먼저 필요한 내용을 글에 반영했습니다. 자세한 참고 자료는 이 글 맨 하단에서 볼 수 있습니다.
1.목소리와 어조: 일상 대화체로 글을 쓰되, 필요 이상으로 구어체 표현을 사용하지 않습니다.
- 지나치게 격식을 차린 말투 대신 일상 대화체로 씁니다.
- 글을 소리 내 읽고, '실제 사람이 하는 말로 들 리는지' 점검합니다.
- 자신의 말투를 그대로 쓰지 않습니다.
- 장황하게 쓰지 않습니다.
2.눈높이: 사용자 관점을 고려해 글을 씁니다.
- 사용자 관심사, 특성, 교육·경험 수준, 글 읽는 시간·장소, 업무환경을 염두에 둡니다.
- 사용자가 궁금해할 만한 정보, 사용자에게 필요한 정보를 선택해서 제공합니다.
- 모든 사용자가 제품과 관련 기술을 전문가만큼 잘 아는 게 아니라는 걸 고려합니다.
- 제품과 관련 기술을 잘 모르는 초보자도 사용법을 쉽게 따라 하도록 씁니다.
3.정확성: 정확한 내용을 씁니다.
- 바르고 확실한 정보를 담습니다.
- 퇴고할 때, 사실을 교차 확인합니다.
- '잘못된 단어나 표현으로 정보를 틀리게 전달하지 않았는지' 점검합니다.
- 글을 발행한 뒤에도 용어, 사용법, 기능 변경 사항을 제때 반영합니다.
4.문장 요건 1: 간결하고 명확하게 씁니다.
- 불필요한 수식어, 조사(~을/~를), 보조용언(~고 있다)을 사용하지 않습니다.
- 주어, 필수 부사어, 목적어 등 필수 문장 성분을 꼭 씁니다.
- 필수 부사어: 문장 구성에 꼭 있어야 하는 부사어
- 예)‘학생들이 학교에 간다’에서 '학교에'가 해당함
- 주체-행위, 주체-속성, 주체-상태 관계를 올바르게 나타내 주술 호응을 이룹니다.
- 예)저 선수의 장점은 주력이 빠르고 시야가 넓은 것이 가장 큰 장점이다(X) → 저 선수의 장점은 주력이 빠르고 시야가 넓은 것이다(O)
- 수식어는 피수식어 바로 앞에 둬 수식 관계를 명확하게 나타냅니다.
- 쉽고, 일상에서 쓰는 단어를 사용합니다.
- 쉬운 단어가 떠오르지 않으면 사전을 찾아봅니다.
- 예)착수하다: “어떤 일에 손을 댐. 또는 어떤 일을 시작함” (사전 정의) → '시작하다'로 바꾸기
5.문장 요건 2: 능동형/피동형 문장, 단문/복문을 적절히 사용합니다.
- 사람과 서비스가 서술어 주체일 때, 능동형 문장(~하다)을 씁니다.
- 기기나 소프트웨어가 서술어 주체일 때, 피동형 문장(~되다)을 써도 됩니다.
- 이중 피동 표현을 사용하지 않습니다.
- 예)잡혀지다(→ 잡히다), 쓰여지다(→ 쓰이다), 읽혀지다(→ 읽히다), 보여지다(→ 보이다), 잊혀지다(→ 잊히다), 찢겨지다(→ 찢기다)
- 글 리듬감을 고려해 단문과 복문을 적절히 섞어 사용합니다.
- 복문: 두 개 이상의 절로 된 문장. 절 하나가 다른 문장 속에 한 성분으로 들어갔거나, 둘 이상의 절이 서로 이어져 여러 겹으로 된 문장
- 단문: 주어와 서술어가 각각 하나씩 있어서 둘 사이 관계가 한 번만 이루어지는 문장
6.번역 투 표현: 영어, 일본어, 중국어에서 온 번역 투 표현을 국어식 표현으로 바꿔씁니다.
- '~적'을 쓰지 않습니다.
- '~의'를 불필요하게 사용하지 않습니다.
- '여러/많은/다양한/모든' 다음에 오는 단어에 '~들'을 붙이지 않습니다.
- ‘기간’ 다음에 '동안'을 쓰지 않습니다.
- '매주/매달/매년’ 다음에 '마다'를 붙이지 않습니다.
- 다음 번역식 표현을 화살표 다음 방향에 있는 표현으로 바꿔씁니다.
- 예)‘~에 의하여’(→ ~이/~가), ‘~로부터’(→ ~에게/~에서), ‘~았었던’(→ ~은), ‘가지다’(→ 있다), ‘~에 대해/관해’(→ ~를), ‘~함에 있어서’(→ ~할 때), ‘~경우에는’(→ ~는), ‘~를 통해’(→ ~해), ‘~중이다’(→ ~하고 있다/~한다)
7.외래어 표기: 국립국어원의 외래어 표기법을 따릅니다.
- 업그래이드 → 업그레이드
- 워크플로우 → 워크플로
- 리포지토리, 레파지토리 → 리포지터리
- 디렉토리 → 디렉터리
- 푸쉬 → 푸시
- 아키텍쳐 → 아키텍처
- 뱃지 → 배지
- 킷 → 키트
- 워크샵 → 워크숍
- 프리젠테이션 → 프레젠테이션
- 어플리케이션 → 애플리케이션
- 버젼 → 버전
- 메뉴얼 → 매뉴얼
- 컨퍼런스 → 콘퍼런스
- 컨텐츠 → 콘텐츠
- 컨셉 → 콘셉트
- 콘트롤 → 컨트롤
- 라이센스 → 라이선스
- 메세지 → 메시지
- 맵핑 → 매핑
- 썸네일 → 섬네일
- 타겟 → 타깃
- 이미 굳어진 외래어는 표기법에 맞지 않아도 유연하게 사용합니다.
- 예) 설루션/솔루션, 크레디트/크레딧, 릴리스/릴리즈
8.(GitLab 관련) 영문 표기: 줄임말과 영문 표기법은 아래 사항을 따릅니다.
- 줄임말이 글에서 처음 나올 때 철자를 모두 풀어서 쓰고, 옆에 괄호를 쳐서 줄임말을 씁니다. 그다음부터는 줄임말만 씁니다.
- 예) 처음 쓸 때는 Continuous Integration(CI), 그다음부터는 CI로 쭉 표기
- GItLab 서비스, 기능, 도구 이름은 영문으로 표기합니다.
- GitLab Free, GitLab Ultimate의 어절 첫 글자를 대문자로 씁니다.
- Prometheus, Kubernetes, Git, The Linux Foundation 등 타사 소프트웨어, 제품, 조직 이름의 어절 첫 글자를 대문자로 씁니다.
- Continuous Integration, Continuous Deployment, Scrum, Agile 등 방법 또는 방법론의 어절 첫 글자를 대문자로 씁니다.
- GitLab 기능은 보통 소문자로 씁니다.
- GitLab 특정 기능이나 도구는 대문자로 씁니다. 관련 사례는 다음 링크를 참조합니다.
- 이상 영문 대문자, 소문자 표기 원칙은 GitLab 문서 스타일 가이드를 따릅니다.
9.전문 용어: 전문 용어(Technical Term)는 꼭 필요할 때 사용합니다.
- 모든 사용자가 전문 용어를 아는 게 아니라는 걸 고려합니다.
- 전문 용어를 꼭 써야 하면 글에서 그 용어를 설명해줍니다.
- 전문 용어를 사용할 때, 상품·서비스·웹사이트·마케팅 등 전반에서 그 용어를 일관되게 씁니다.
- 특정 산업이나 직종 관계자를 상대로 글을 쓸 때, 해당 산업 또는 직종 관련 용어를 사용합니다.
10.퇴고: 다음 절차를 거쳐 글을 수정합니다.
- 글을 완성하고 휴식을 취한 뒤, 이를 다시 읽어봅니다.
- 글을 완성한 지 몇 시간 뒤, 또는 그다음 날 읽어도 좋습니다.
- 데스크톱으로 글을 작성했으면 스마트폰이나 태블릿 PC로 글을 읽습니다. 글을 출력해서 읽어도 좋습니다.
- 글을 앉아서 읽거나, 서서 읽거나, 이동하면서 읽어도 됩니다.
- 로컬 환경에서 작성한 글을 웹에 올린 뒤, 온라인에서 꼭 다시 읽어봅니다.
- 글을 소리 내 읽고, 어떻게 들리는지 확인합니다.
- 한 번에 한 문장을 읽습니다.
- 말 하기 불편하거나 어색하게 들리는 문장을 고칩니다.
- 호흡이 불편할 만큼 긴 문장을 짧은 문장들로 나눕니다. 복문을 단문으로 바꿉니다.
- 글을 여러 번 반복해서 읽고 단어, 문장, 내용이 적절한지 검토합니다.
- '문장을 한번 읽으면 의미를 바로 이해할 수 있는지', '내용이나 표현이 어려운지', '이 글이 독자에게 유용한지' 독자 입장에서 생각합니다.
- 동료나 고객에게 글 피드백을 요청합니다.
- 초보자를 대상으로 글을 쓰면 초보자를 리뷰어로 삼습니다.
- 개발자를 대상으로 글을 쓰면 개발자를 리뷰어로 삼습니다.
- 리뷰어에게 '글 내용이 잘 이해되는지', '글 흐름이 괜찮은지', '추가할 내용은 없는지' 등을 묻습니다. 피드백이 필요한 내용을 구체적으로 질문해도 좋습니다.
- 내용이 정확한지 점검합니다. 부정확한 내용은 바로잡습니다.
- 참고 자료를 보고 글을 썼다면 이 자료와 글을 교차 확인하며 정확성을 검토합니다.
- 특정 기능을 글에서 다뤘다면 '이 기능이 글 내용대로 작동하는지' 테스트합니다.
- '기능·메뉴 이름이나 화면 내용이 글 내용과 같은지' 확인합니다.
- 뜻이 불분명한 문장을 명확하게 바로 잡습니다.
- 뜻을 모호하게 하는 단어, 문장은 뜻을 분명하게 나타낸 단어, 문장으로 바꿉니다.
- 이밖에 불필요하거나 중복되는 단어, 문장, 내용을 지웁니다.
- 오탈자, 띄어쓰기, 외래어 표기 오류를 확인합니다.
- 맞춤법 검사기로 오탈자, 띄어쓰기 오류를 확인합니다.
- 추천 도구: 부산대 맞춤법 검사기, 다음 맞춤법 검사기
- 헷갈리는 맞춤법 원칙은 ‘한글 맞춤법’ 페이지에서 확인합니다.
- 국립국어원 외래어 표기법 용례를 보고, 외래어 표기 오류를 확인합니다.
- 맞춤법 검사기로 오탈자, 띄어쓰기 오류를 확인합니다.
마무리하며
지금까지 정확하고, 잘 읽히며, 유용한 기술 문서를 쓰기 위해 고려할 사항을 살펴봤습니다. 이 가이드는 지금 실무에 바로 활용할 테크니컬 라이팅 원칙을 담았습니다. 기술 문서를 쓰면서 자주 겪는 문제를 바로 잡기 위해 유념할 사항을 다뤘습니다. 이에 문장과 표기법 내용이 주를 이루고요. 특히 쉽게 읽히는 문장을 쓰는 방법을 자세히 담았습니다. 이 가이드는 할 일 목록(To-Do List) 형태로 작성했습니다. 각 항목을 체크하며 글을 퇴고하거나 콘텐츠 작업을 회고하도록 의도했습니다.
이 가이드는 당장 활용할 테크니컬 라이팅 원칙을 중심으로 내용을 추렸습니다만. 분량이 깁니다. 그러나 긴 내용에 압도되지 않으면 좋겠습니다. 가이드를 100% 지키지 못했다고 해서 자괴 감을 느끼지 않아도 됩니다. 이번에 부족한 점은 다음에 보완하면 됩니다. ‘인생은 한방이 아니라 계단식으로 성장한다’는 말이 있습니다. 테크니컬 라이팅도 마찬가지입니다. 콘텐츠 작업 도중에 이 가이드를 보고 업무에 활용해도 좋습니다만. 콘텐츠 작업이 끝난 뒤, 이를 보면서 다음 작업에 보완할 점을 도출할 수도 있습니다.
인포그랩의 테크니컬 라이터는 글로 DevOps와 인포그랩 엔지니어, 고객을 연결합니다. 아울러 우리 엔지니어와 고객의 원활한 DevOps를 돕고 있습니다. 올바른 테크니컬 라이팅으로 회사와 고객의 성공적인 DevOps에 기여하겠사오니 많은 관심 부탁드립니다.
<참고 자료>
1.「테크니컬 라이팅의 7가지 원리」(토마스 E.피어설·켈리 카길 쿡, 북코리아, 2013)
2.「스타일과 목적을 살리는 웹 글쓰기」(니콜 펜튼·케이트 키퍼 리, 길벗, 2016)
3.「번역자를 위한 우리말 공부」(이강룡, 유유, 2014)
4.Microsoft Style Guide
5.Google Developer Documentation Style Guide
6.GitLab Documentation Style Guide
7.카카오엔터프라이즈 테크니컬 라이팅 콘텐츠
8.NHN 클라우드 테크니컬 라이팅 콘텐츠
9.토스 라이팅 콘텐츠
10.텍스트리 ‘소프트웨어(SW) 기술 문서의 유형’
11.한겨레신문 ‘김형배의 어법특강’
12.한빛출판네트워크 ‘[책쓰기 & 글쓰기] 흔한 번역투 TOP 12’