Homebrew

iTerm2

HTTP 완벽 가이드

애자일 소프트웨어 장인 정신

Clean Code 클린 코드

하드웨어와 소프트웨어에 숨어 있는 언어

CODE 코드

시작하며
안녕하세요. 카카오엔터프라이즈 테크니컬라이팅팀의 Crystal(김유리)과 Sandy(차신영)입니다.
 
그 동안 테크니컬커뮤니케이션 팀에서는 테크니컬 라이팅 4대 원칙과 언어학 관점에서 기술문서 가독성 향상 전략 등 테크니컬 라이팅과 관련한 정석적인 주제를 다뤘었는데요. 며칠 전 개발자 한 분께서 "테크니컬 라이팅 교육을 받고 싶은데 시간은 없고.. 어떻게 하면 기술 문서를 잘 쓸 수 있을까요? 혹시 간단한 팁이 있을까요?" 라는 질문을 주셨습니다.
 
 생각해보면 개발자들이 많은 시간을 들여 테크니컬 라이팅을 심도있게 공부하기는 현실상 쉽지 않은 게 사실인데요. 그래서 오늘은 수 많은 테크니컬 라이팅의 이론과 팁 중에서도 기술문서 작성에 관심이 있으신 개발자 분들이라면 꼭 알아야 할 10가지 팁을 간추려 소개하겠습니다.
 
 
 
테크니컬 라이팅 10계명
• Tip 1. 필수 문장 성분 생략하지 않기
기술문서 초안을 리뷰하다 보면 간단한 문장이라도 필요한 문장 성분 특히 주어(~은/는/이/가), 필수적 부사어(~에, ~에게), 목적어(~을, ~를)가 생략되어 정확한 의미를 파악할 수 없는 경우를 많이 보게됩니다. 다음 예시를 살펴 볼까요?
원문에서의 문장은 겉보기에는 이상이 없어 보일 수 있습니다. 하지만 문장을 자세히 들여다 보면 주어, 필수적 부사어, 목적어가 생략되어 있음을 알 수 있습니다. 즉, 누가 누구에게 Recognizer.ExpectSpeech Instruction을 전송한다는 건지 Service Agent가 무엇을 수신한다는건지 정확히 알 수 없습니다. 바로 주어, 필수적 부사어, 목적어 등이 생략되어 있기 때문인데요. 특히 Request와 Response가 분명한 API 레퍼런스나 복잡한 순서를 설명하는 문장에서 이런 필수 문장 성분들이 생략되어 있다면 독자는 해당 기능을 쉽게 파악할 수 없게 됩니다.
 
기술문서가 아닌 다른 형태의 글에서는 주어와 서술어가 생략되어도 맥락상 큰 문제가 없을 수도 있지만, 기술문서에서는 행동 주체와 그 행동을 받는 주체, 목적어가 명확히 구분되어야 하기 때문에 주어(~은/는/이/가), 필수적 부사어(~에게), 목적어(~을/를) 등을 반드시 명시하는 것이 좋습니다. 
 
• Tip 2. 문장 성분의 호응 지키기
문장 안에는 여러 문장 구성 성분들이 존재하며 이들이 자연스럽게 호응될 때 좋은 문장이라고 할 수 있습니다. 특히 주어와 서술어, 수식어와 피수식어, 부사어와 서술어의 호응 관계에 주의하여 문장을 작성해야 하는데요. 만약 문장 성분들이 서로 호응하지 않으면 의미가 불분명하고 모호하게 전달될 수 있습니다. 
 
주어와 서술어
주어와 서술어의 호응은 주체-행위, 주체-상태, 주체-속성의 관계를 올바르게 표현하는 것입니다. 아래 예시를 보면 주체와 속성의 관계가 올바르게 표현되지 않은 것을 확인할 수 있습니다.
예시의 원문이 어색한 이유는 '이유'란 '어떠한 결론이나 결과에 이른 까닭이나 근거/구실이나 변명'을 의미하는 명사인데, 이 명사와 호응이 되지 않는 서술어가 나왔기 때문입니다. 따라서 주어와의 호응에 따라 '~이기 때문이다', '~이다', '~한 것이다' 등의 서술어를 사용해야 합니다.
 
수식어와 피수식어
수식어와 피수식어의 호응은 꾸미는 말과 꾸밈을 받는 말의 관계를 분명하게 표현하는 것입니다. 꾸미는 말의 대상이 명확하지 않으면 이또한 전달하고자 하는 의미가 모호해질 수 있는데요. 
 
원문에서 '복잡한'이 수식하는 대상이 '소프트웨어'인지 '설치과정'인지 불분명합니다. 만약 '복잡한'의 대상이 설치 과정일 경우, '복잡한'의 위치를 적절히 옮겨 명확한 문장으로 수정할 수 있습니다. 
 
부사어와 서술어
어떤 부사는 특정 표현과 호응할 때 자연스럽기 때문에 글을 쓸 때 부사어와 서술어의 호응에 유의해야 합니다. 예를 들면, '반드시'의 경우는 긍정의 서술어와 호응할 때 자연스러우며, '결코'나 '절대로'는 부정의 서술어와 호응할 때 자연스럽습니다.
'표준국어대사전'에서는 '절대로'를 '어떠한 경우에도 반드시'로 뜻풀이하고, '세상에 절대로 공짜라는 것은 없다./절대로 나쁜 일을 해서는 안 된다./그는 절대로 상대해서는 안 될 사람이다.'의 용례를 보여주고 있는데요. 이처럼 '절대로'는 주로 부정(-지 않다 등)을 나타내는 말과 호응하는 것이 자연스러우며, 긍정을 나타내는 서술어와 호응하고자 한다면 '틀림없이 꼭'이라는 뜻을 가진 '반드시'를 대신하여 사용하는 것이 자연스럽습니다.
 
• Tip 3. 조사 올바르게 사용하기
조사는 주로 명사에 붙어서 다른 말과의 관계를 나타내거나 특별한 뜻을 더해 주는 품사인데요. 조사는 문장에서 아주 작은 부분만을 차지하고 있지만, 내용을 모르는 독자가 꼼꼼히 읽다 보면 조사 때문에 의미 파악이 어려워지는 경우가 많습니다. 게다가 필요하지 않은 조사를 쓰면 문장이 길어지고 읽기 힘들어지기 때문에 없어도 이해하는데 문제가 없는 조사들은 과감히 생략해야 합니다. 
 
불필요한 조사 생략
SDK 다음에 굳이 '를'이라는 조사가 오지 않아도 이해하는데 문제가 없습니다. 이처럼 불필요한 조사가 들어가게 되면 문장의 전달력과 가독성이 떨어지므로 반드시 문장을 완성한 뒤 불필요한 조사가 들어가 있지는 않은지 확인을 하는 것이 좋습니다.  
 
영어 발음에 맞는 조사 사용
영단어 뒤에 조사를 사용할 때에는 영어 발음에 맞는 조사를 사용해야 합니다. 다음 예시에서 Writing(라이팅)의 발음에 맞는 조사는 '는'이 아닌 '은' 이므로 조사 변경이 필요합니다.
 
소괄호 앞에 오는 단어에 맞는 조사 사용
소괄호가 있는 단어에 조사를 사용할 때에는 소괄호 바로 앞에 오는 단어에 맞춰 조사를 사용합니다. 아래 예시에서 조사는 괄호 안이 아닌 괄호 앞에 위치한 Language(랭귀지)에 맞춰야 하므로 올바른 조사는 ‘는'이 됩니다. 
• Tip 4. 피동형/사동형 지양하기
영어식 문장에서는 무생물을 주어로 하여 피동형이나 사동형 표현이 우리말보다 일반적이지만, 우리말 표현에서는 이런 표현들이 어색할 때가 있습니다. 따라서 인물을 주어로 하여 자연스러운 우리말 표현이 가능한데도 무생물을 주어로 내세워 사동 표현이나 피동 표현으로 쓰는 경우는 지양해야 합니다. 기술문서에서 피동형/사동형 문장은 번역 투의 느낌이 강해지기 때문에 부자연스럽다는 느낌을 줄 수 있고, 특히 피동 표현은 책임 회피의 부정적 태도가 있어 의도한 것과 다르게 문장의 의미가 전달될 수 있습니다. 따라서 꼭 필요한 경우가 아니라면 피동형과 사동형은 지양해야 합니다. 
 
예시의 원문에서 '클릭되어야'는 불필요한 피동형 표현으로, 버튼은 사람이 주체가 되어 클릭하는 것이기 때문에 피동형 표현을 능동형으로 수정하면 더 자연스러운 문장이 됩니다. 
• Tip 5. 이중 부정 지양하기
표준국어대사전에 따르면 이중 부정이란 한 번 부정한 것을 다시 한 번 부정하여 긍정을 나타내는 것을 뜻합니다. 이중 부정을 쓰면 한 번 부정한 내용에 대해서 다시 또 부정해야 하기 때문에 문장이 불필요하게 복잡해질 수 있는데요. 이 경우, 독자가 문장을 읽고 이해하는 데 시간이 더 오래 걸리고 문장의 의미도 모호해질 수 있습니다. 따라서 기술문서에서는 가능한 이중부정 대신 긍정문을 사용하여 간결하고 명료한 표현을 사용하는 것이 바람직합니다. 
 
다음 예시를 보면, 원문은 휴게시간이 소정근로시간에 포함된다는 내용이지만 이중 부정을 사용하여 한 번 더 생각해야 정확한 의미를 파악할 수 있습니다. 기술문서에서 이중 부정은 지양해야 하므로 이중 부정을 긍정문으로 수정할 경우 내용을 훨씬 명확하게 알 수 있습니다.
• Tip 6. 명확한 표현 사용하기
기술 문서를 작성할 때에는 초급 개발자들도 문서를 쉽게 이해할 수 있도록 명확하고 구체적인 표현을 사용해야 합니다. 뜻 자체가 모호한 표현이나 여러 해석이 가능한 표현을 사용하면 작성자의 의도와 다르게 독자가 받아들일 수 있습니다. 따라서 기술 문서 작성 시 모든 독자에게 하나의 동일한 의미가 전달될 수 있도록 명확한 표현을 사용하여 작성해야 합니다. 
 
구체적인 수치 활용
어떤 정도에 대해 표현하는 문장에서 정확한 시간이나 양과 같은 수치를 "추상적으로 표현하면" 의미 전달이 모호해질 수 있습니다. '조금', '잠시', '많이', '꽤', '곧' 등과 같은 추상적인 표현을 사용해 ‘정도’를 나타내는 경우, 독자마다 다르게 생각하여 혼선을 빚을 수 있습니다. 따라서 어떤 정도를 표현해야 하는 경우, 수치를 활용하여 표현하면 정도를 구체적으로 명시할 수 있기에 의미가 보다 명확하게 전달될 수 있습니다.
 
예시의 '많은 시간'이란 표현도 사람마다 다르게 이해할 수 있고, 도대체 어느 정도의 시간이 필요한지 가늠하기 어렵습니다. 이러한 경우 아래 문장처럼 '시간/분/초'와 같은 시간단위를 활용하여 수치로 나타내면 보다 명확한 표현이 됩니다.
 
여러 해석이 가능한 표현 지양
우리가 일상적으로 사용하는 표현 중에는 의미가 정확하지 않고 여러 의미로 해석될 수 있는 표현들이 있습니다. 기술문서에서 이런 단어들을 그대로 사용하다 보면 독자에게 명확한 의미 전달이 어렵기때문에 이런 표현을 사용하지 않는 것이 좋습니다. 
위 예시에는 모호한 표현이 두 개나 포함되어 있는데요. 원문에 따르면 시스템상에서 주 52시간 근무 제한을 적용하는 설정에 대한 설명인데, 근무시간에 도대체 어떤 영향을 준다는 것인지 직관적으로 알 수 없습니다. '주 52시간 넘게'라는 표현도 52시간을 포함하는 것인지 아닌지가 불분명합니다. 수정문에서는 해당 설정이 최대 근무시간 설정에 정확히 어떤 영향을 주는지 알 수 있고, 주 52시간까지 포함해서 근무시간을 설정할 수 있다는 점을 더 명확히 전달할 수 있습니다.  
 
대상을 명확히 지칭
기술문서에서는 지시 대상을 명확하게 구분해 정보를 정확하게 전달해야 합니다. 예를 들어, 한 문서에서 두 종류의 서버가 언급되는 경우 단순히 서버라고 지칭하지 않고 어떤 서버인지 구체적으로 명시합니다.
예시에서는 어느 서버에서 요청을 받아서 고객사 서버로 전달하는지 파악하기 어렵습니다. 고객사 서버에서 온 요청을 다시 고객사 서버로 보내는 것인지, 아니면 다른 서버인지 정확히 명시되어 있지 않습니다. 따라서 대상을 명확히 지칭할 수 있도록 하는 것이 중요합니다.
• Tip 7. 순서와 목록 구분하기
문서를 작성하다 보면 순서를 설명하는 경우(순서가 있는 목록)와 단순히 목록을 나열하는 경우(순서가 없는 목록)가 발생합니다. 테크니컬라이팅을 접하지 않으신 분들이라면 순서가 있는 목록과 순서가 없는 목록을 숫자와 글머리 기호 등을 혼용하여 글을 작성하실 수도 있는데요. 테크니컬 라이팅에서는 순서가 있는 목록에는 숫자를 사용하며, 순서가 없는 목록에는 글머리 기호 또는 하이픈 등을 사용하는 것이 일반적입니다. 이 두 경우를 서로 혼용하게 되면 독자에게 혼란을 줄 수 있기 때문에, 순서가 있는 목록과 순서가 없는 목록을 구분하여 글을 작성하는 것이 좋습니다.
 
• Tip 8. 개조식 활용
기술 문서를 작성 할 때 대부분의 경우에 '~다'로 끝나는 서술식 문장을 사용하는 것이 일반적입니다. 하지만 테이블이나 간단한 안내 항목 등에서 '~다'의 종결 어미 대신 명사나 용언의 명사형(예: ~임, ~함)으로 문장을 끝내는 개조식과 글머리 기호 또는 하이픈 등을 적절히 사용하면 문서의 가독성을 높일 수 있습니다. 다음 예시에서 처럼 문장이 길게 서술되어 있어 내용을 파악하기 힘든 경우, 개조식 형태와 하이픈을 사용해 가독성을 개선할 수 있습니다.  
• Tip 9. 맞춤법/띄어쓰기 체크하기
며칠을 고생해서 만든 PPT 문서를 발표하려고 문서를 열었는데 오타를 발견해서 당황한 경험, 고객사로부터 전달받은 문서에 맞춤법 오류가 있어 문서에 대한 신뢰도가 떨어진 경험... 다들 한번 쯤은 있으실 텐데요. 
 
기술문서가 얼마나 잘 쓰여졌는지와는 상관없이 해당 문서에 맞춤법, 띄어쓰기, 오타 등의 오류가 있다면 해당 문서가 빛을 잃는건 한 순간입니다. 그래서 저희 팀에서도 문서 최종 릴리즈 시점에 이런 오류를 잡아내기 위해 몇 번의 리뷰 과정을 거치는데요. 다음과 같이 자주 틀리는 맞춤법을 공부해 두면 글을 쓸 때 도움이 될 수 있습니다.
 
 
하지만 단 시간에 모든 맞춤법이나 띄어쓰기 용법을 독파하는 것은 쉽지 않습니다. 또한 사람의 눈으로 이런 오류를 단시간에 모두 찾아내는 건 꽤 어려운 작업이기 때문에 저희 팀에서는 맞춤법 검사기를 보조 수단으로 사용하고 있습니다. 맞춤법 검사기를 사용하다보면 자연스럽게 내가 자주 틀리는 맞춤법이나 띄어쓰기가 무엇인지 파악하게 될 것이고, 결과적으로 이런 오류는 점차 줄어들게 될 것입니다. 맞춤법이나 띄어쓰기 용법을 공부하여 하나씩 적용해 보는 것도 좋지만, 이런 시간이 부족하다면 문서를 최종적으로 완성하기 전에 반드시 맞춤법 검사기를 사용해 보실 것을 추천드립니다.
 
• Tip 10. 외래어 표기 체크하기
맞춤법과 마찬가지로 자주 틀리기 쉬운 외래어도 알아두면 좋은데요. 특히 애플리케이션(어플리케이션 X), 비즈니스(비지니스 X) 처럼 회사 뿐만 아니라 일상적으로 사용하는 단어를 계속 잘못된 표기법으로 사용하고 있다면 조금 억울하지 않을까요? 모든 단어의 정확한 외래어 표기를 익히는건 어렵더라도, 적어도 업무 중 자주 사용하고 있는 외래어 표기는 한번쯤 눈여겨 보는 것을 추천드립니다. 이 밖에 외래어 표기는 국립국어원이 운영하는 한국어 어문 규범에서 확인할 수 있습니다.
 
 
마치며
지금까지 개발자들을 위한 테크니컬라이팅 10계명이라는 주제로 국문으로 기술 문서를 작성할 때 알아두면 좋은 팁들을 소개해 드렸는데요. 포스팅 길이를 염두에 두다 보니 기술 문서를 작성할 때 자주 틀리게 되는 내용 위주로 포스팅을 구성하게 되었습니다. 
 
이번 포스팅을 재미있게 읽으셨다면, 시중에 나와있는 테크니컬라이팅 서적들도 한 번 읽어보시는 것을 추천드립니다. 막연하게 테크니컬라이팅은 어렵다라고 생각하기 보다는 위에서 강조드린 팁들 부터 하나씩 실전에 적용해 보다 보면 문장에 대한 논리, 논리적 연결 관계, 가독성과 같은 주제에 자연스럽게 관심을 가지실 수 있을 것입니다. 개발자들에 있어 개발만큼이나 문서화의 중요성도 강조되고 있는 요즘, 오늘 포스팅이 작은 도움이 되면 좋겠습니다. 감사합니다.
 
 
  테크니컬 라이팅 관련 글 더보기  
     ✓ 목차의 중요성
     ✓ 기술 문서 작성 5단계
     ✓ 테크니컬 라이팅 4대 원칙 
     ✓ 기술 문서 쉽게 쓰기 지침
     ✓ 언어학 관점에서의 기술문서 가독성 향상 전략 
     ✓ 카카오 i 기술문서 사이트 여정, 그리고 벌써 한 달 
     ✓ Technical Writer에서 Technical Communicator로...  
     ✓ [KREW INSIDE] AI 서비스의 기술 문서를 책임지는 사람들, 테크니컬 라이터 
 
 
 
참고 문헌   
[1] 이공계 Technical Writing 가이드(북코리아)
[2] 웹 기획자가 알아야 할 서비스 글쓰기의 모든 것 (위키북스)
[3] 국립국어원 홈페이지
[4] 이공계는 글쓰기가 두렵다 (마이넌)
[5] 독서와 문법 II(지학사)
 
김유리(Crystal)
사용자의 입장에서 생각하고, 개발자와 원활한 소통을 할 수 있는 Communication Skill을 가진 Technical Communicator입니다. 카카오엔터프라이즈의 값진 기술들을 정확하고 명확하게 전달하고, 신뢰를 쌓을 수 있는 문서를 만들고자 합니다. 
차신영(Sandy)
산더미처럼 쌓여진 문서 정리, 새로운 문서화 도구 테스트, 그리고 구글링이 취미인 Technical Communicator입니다.

개발자들을 위한 테크니컬 라이팅 10계명 #기술문서_작성법#개발자_글쓰기 #테크니컬라이터

사람을 찾고 함께 성장하는 길

WooSeok Suh

WooSeok Suh

책

슬라이드

앱

글

개발자들을 위한 테크니컬 라이팅 10계명 #기술문서_작성법#개발자_글쓰기 #테크니컬라이터