Know-how, News Today

바쁜 개발자를 위한 테크니컬 라이팅 10계명

비대면 확장으로 글과 영상 활용도가 예전에 비해 높아진 듯합니다. 특히 산업 측면에서 볼 때 고객이 우리 홈페이지나 모바일 페이지에 처음 접속해 원하는 정보를 찾는 등 행동하는 글쓰기를 적용하기 위해서는 고객 중심 테크니컬 라이팅이 중요하다고 할 수 있겠죠. 웹 개발자 역시도 테크니컬 라이팅, 즉 기술문서를 잘 쓰고 픈 욕심이 있습니다. 마침, 카카오엔터프라이즈 홈페이지에 테크니컬 라이팅팀이 정리한 ‘개발자를 위한 테크니컬 라이팅 10계명’이 있어 이를 요약, 정리했습니다. 기술 문서 중심으로 한번 정리해볼까요?
(기사 마지막에 보너스 콘텐츠가 있어요~)

글. 김관식 기자 seoulpol@wirelink.co.kr

1. 필수 문장 생략하지 않기

<원문>을 가만히 보면 때문에 주어(~은/는/이/가)와 필수 부사어(~에게), 목적어(~을/를)가 생략됐어요. 누가, 누구에게 Recognizer.ExpectSpeech Instruction을 전송한다는 건지, Service Agent가 무엇을 수신하는 건지 정확히 알 수 없죠. 이에 대해 라이팅팀은 “Request와 Response가 분명한 API 레퍼런스나 복잡한 순서를 설명하는 문장에서 이런 필수 문장 성분들이 생략되어 있다면 독자는 해당 기능을 쉽게 파악할 수 없다”고 강조합니다. 기술문서는 행동 주체와 그 행동을 받는 주체, 목적어가 분명해야 확실하게 메시지를 전달할 수 있기 때문에 주어와 필수 부사어, 목적어(~을/를)를 꼭 넣어주어야 이해하기가 쉽답니다.

2. 문장 성분 호응 살피기

1) 주어-서술어

위 글은 주어와 서술어의 호응 사례다. 라이팅팀은 주어와 서술어의 호응에 대해 “주체-행위, 주체-상태, 주체-속성의 관계를 올바르게 표현하는 것”이라고 말합니다. 그렇게 대입하면 위 사례는 ‘주체-속성’에서 올바르지 못한 문장입니다.

<원문>을 보시면 ‘~이유는’-‘비슷하다’ 사이의 호응, 즉 이유에 대한 근거나 구실, 변명 등이 뒤이어 나와야 하는데 그렇지 않죠. 호응에 맞춘다면 ‘~이기 때문이다’ ‘~이다’ ‘~한 것이다’ 등의 서술어를 넣어야 합니다.

2) 수식어-피수식어

수식어와 피수식어 간의 호응이 중요한 이유는 문장의 의미를 제대로 전달하기 위해서입니다. 가급적 수식어는 수식 받는 말 앞에 배치하면 서로의 관계를 분명히 매듭지을 수 있어요. <원문>의 ‘복잡한’이 수식하는 대상이 소프트웨어인지, 설치 과정인지 모호하죠. 반면 <수정문>처럼 ‘복잡한’의 대상이 설치 과정이라면 자리를 재배치해 의미를 명확히 할 수 있답니다.

3) 부사어-서술어

부사마다 자연스럽게 호응하는 서술어가 있습니다. 특히 일상에서 자주 사용하는 것처럼 ‘절대로’ ‘결코’ 등의 부사어는 부정문과, ‘반드시’는 긍정문과 호응해야 문맥이 자연스레 연결됩니다.

3. 올바른 조사 사용하기

조사를 올바르게 사용하거나 생략하는 것만으로 문장은 한 층 더 매끄럽게 연결됩니다. 그럼 예를 보며 함께 살펴볼까요?

<원문>에서 ‘초기화’ 뒤에 조사 ‘를’을 넣지 않아도 문맥에 이상 없지요. 영단어 뒤에도 영어 발음에 맞는 조사를 넣습니다. Writing(라이팅) 뒤에 조사를 넣는다면 ‘~은’을 넣습니다. 만약 소괄호가 있는 문장이라면 소괄호는 무시하고 바로 괄호 앞에 있는 단어에 맞춰 조사를 사용합니다.

4. 피동형/사동형, 피해야

한글을 우수하기 때문에 피동형으로 쓰지 않아도 돼요. 게다가 피동형을 벗어나 능동으로 문장을 작성하면 더 힘있는 글을 쓸 수 있어요. ‘문이 열렸다(피동)’와 ‘내가 문을 열었다(능동)’이라는 문장을 볼까요? 어때요, 느낌이 살짝 다르지요?

능동태를 지향해야 하는 이유는 바로 행위의 주체가 살아있기 때문입니다. 굳이 무생물을 주어로 내세워 사동/피동으로 쓸 필요가 전혀 없어요.

위 문장의 <원문>을 보면 ‘클릭되어야’라는 표현은 필요 없어요. 사람이 주체라면 ‘클릭해야’로 써야합니다.

5. 이중 부정 사용 않기

이중 부정을 쓰게 되면 부정에 부정을 연결해 긍정을 나타내는 표현이라 글이 늘어집니다. 또한 복잡하며 독자는 문장을 읽고 이해하는 데 정확한 뜻을 파악하기 어려울 수 있습니다. 이중부정 대신 하나의 긍정을 나타낸다면 더욱 간결하고 명료한 문장을 쓸 수 있습니다.

6. 명확하게 표현하기

기술 문서는 특히 더 이해하기 쉽도록 작성해야 합니다. 모호한 표현이나 여러 해석이 가능한 문장은 그만큼 여러 뜻의 문장을 나타냈습니다. 하나의 동일한 의미를 전달할 수 있어야겠죠. 가급적 추상적인 조금 잠시 많이 꽤 표현보다 구체적인 수치를 나타낼 수 있으면 좋습니다.

문장의 의미를 정확하게 하기 위해 지시대상을 확실히 가리키는 것도 중요합니다.

7. 순서와 목록 구분하기

테크니컬 라이팅에서는 순서가 있는 목록에는 숫자를 사용하며 순서가 없는 목록은 글머리 기호나 하이픈 등을 사용합니다.

8. 개조식 활용하기

대개 기술문서를 작성할 때 ‘~다’로 끝나는 경우가 많습니다. 다만, 테이블이나 간단한 안내 항목 등에서는 명사나 용언의 명사형(~임, ~함)으로 작성하는 개조식과 글머리 기호/하이픈 등을 적절히 사용하면 가독성을 높일 수 있습니다.

9. 맞춤법과 띄어쓰기 체크하기

사랑하는 연인이 맞춤법이 계속 틀리면 어떨까요? 확 깨죠. 마찬가지입니다. 기술문서는 잘 작성하는 것도 중요하지만 기본적인 맞춤법과 띄어스기, 오탈자를 꼼꼼히 체크해야 합니다. 자주 틀리는 맞춤법은 따로 메모했다가 자주 확인해 실수가 없어야 합니다.

다음 맞춤법 검사기나라인포테크 문법 검사기를 사용해도 좋습니다.

10. 외래어 표기 체크하기

맞춤법 못지 않게 자주 틀리는 외래어도 평소 챙겨두면 좋습니다. 어플리케이션(애플리케이션의 잘못), 비지니스(비즈니스의 잘못), 컨텐츠(콘텐츠의 잘못), 콘트롤(컨트롤의 잘못) 등의 실수를 다음엔 반드시 틀리지 않도록 해야 해요. 외래어 표기는 국립국어원에서 운영하는 한국어 어문 규범을 활용하면 좋습니다.

이상으로 카카오에서 제공하는 테크니컬 라이팅에 필요한 10가지를 살펴봤습니다. 기술문서가 쉽지 않겠지만 갈수록 독자는 디지털화되고 있고 그만큼 가독성과 명확성을 확보하는 것을 우선적으로 고려하게 됩니다. 개발자도 테크니컬 라이팅을 이해할수록 독자에 맞는 디지털 서비스를 제공할 수 있겠죠. 행운을 빕니다.

추신. 아래는 독자 여러분이 참고하면 좋은 UX 라이팅 관련 기사입니다. 함께 탐독해주시면 도움이 될 것이라 믿습니다.

Comments
© DIGITAL iNSIGHT 디지털 인사이트. 무단전재 및 재배포 금지

뉴스콘텐츠는 저작권법 제7조 규정된 단서조항을 제외한 저작물로서 저작권법의 보호대상입니다. 본 기사를 개인블로그 및 홈페이지, 카페 등에 게재(링크)를 원하시는 분은 반드시 기사의 출처(로고)를 붙여주시기 바랍니다. 영리를 목적으로 하지 않더라도 출처 없이 본 기사를 재편집해 올린 해당 미디어에 대해서는 합법적인 절차(지적재산권법)에 따라 그 책임을 묻게 되며, 이에 따른 불이익은 책임지지 않습니다.

Related Posts