테크니컬 라이팅 원칙 정리

카카오 테크니컬 라이터 "정나래"님의 강연 내용을 바탕으로 정리함

커뮤니케이션의 중요성

• 다들 동일한 것을 이해하고 있다 생각하지만, 그렇지 않을 수 있다
• 이번 강연에서는 텍스트 커뮤니케이션을 중심으로 이야기해 볼 것

테크니컬 라이팅이란?

• 텍스트 커뮤니케이션의 일종
  • 말로 하는 소통의 한계 극복 가능
  • 휘발성인 말과는 다르게 텍스트가 남는다
  • 반복되는 설명 대신 가능, 뒤늦게 합류하는 이에게 맥락을 제공할 수 있다
  • 그래서 맥락을 모르는 이들도 이해할 수 있게, 명확하고 쉽게 서술해야 한다
• 복잡한 기술 정보를 명확하고, 간결하게 문서화하는 글쓰기 기술
• 읽는 사람이 원하는 목적을 달성할 수 있도록 필요한 정보를 쉽게 전달하는 것이 목표!
• 독자 입장에서 쓴 글
• 기술 문서는 누가 읽어도 같은 의미로 이해되도록 명확해야 한다!!
• 이중적으로 해석되는 모호한 글이 되지 않도록 신경써서 작성하기
• prewriting, planning, drafting, recollection, review, revision, proofreading
  • 테크니컬 라이팅을 담당하는 그룹이 아니라면 이 모든 과정을 적용하기는 힘들다

계획 -> 작성 -> 수정

• 혼자 글을 쓰면 계획과 수정 단계를 빠뜨리는 경우가 많다
• 계획 / 작성 / 수정에 시간과 자원 배분을 40% / 20% / 40%

계획 단계

: 계획 단계에서는 주제, 목적, 독자, 구조를 생각해보기

• 주제: 무엇에 대해 쓸 것인가?
• 목적: 이 글을 왜 쓰는지
  • 누군가를 이해시키기 위한 것인지
  • 사용법을 설명하기 위해서인지
  • 고객사나 윗사람을 설득하기 위해서인지
• 독자: 누가 읽을 것인가?
  • 독자가 목적을 달성할 수 있도록. 상대방의 눈높이에 맞추는 것이 중요
  • 독자를 명확히 하는 것이 중요!
    • 다른 기업의 최고경영자, 서비스를 이용하는 엔드 유저, 개발자(이 기술을 처음 접하는 개발자 / 어느정도 배경 지식이 있는 개발자)
• 구조: 어떻게 쓸 것인가?
  • 사용법을 안내하는 글이라면, 시간의 흐름에 따라 절차를 안내하는 글이 좋을 것 (절차 기반 구조)
  • 기술 블로그 같은 경우, 서론 - 본문 - 참조 (서술형 구조)
  • API 문서같은 경우, 계층 구조를 따라 정보를 나열하는 것이 좋을 것 (라이브러리 구조)
  • 시스템 기반의 구조를 설명하는 글이라면 공간에 따른 안내
  • 공통적으로 적용되는 것?
    • 큰 그림을 먼저 그리고, 세부적인 내용을 이어갈 것 (숲을 먼저, 그 뒤에 나무를)
    • 배경 정보나 전체 윤곽을 먼저 설명하고, 세부적인 내용을 설명하는 순서로 문서를 구조화하는 것이 좋다
    • MECE 기법을 활용
      • 중복되지 않고, 빠진 부분이 없는 구조
      • MECE 기법을 활용하면, 독자가 이해하기 쉬운 글을 쓸 수 있다
• 계획 단계에 투자를 많이 해야 글이 나중에 다른 방향으로 새지 않도록 할 수 있다!

초안 작성 단계

• 작성한 목차를 토대로 내용 채우기
  • 이때, 계획 단계에서 생각한 독자의 입장을 고려해 작성

1. 사용자를 이해시키는 것이 핵심이기 때문에, 두괄식으로 작성하기
2. 가장 중요한 정보를 먼저!
3. 핵심 정보 이후에, 이해를 위해 필요한 세부 뒷받침 내용들을 배치
4. 마지막으로 글의 후반부에 더 알면 좋은 정보들을 배치
   • 독자들은 생각보다 집중력이 짧다. 나머지 내용들이 읽혀지지 않을 수 있다고 가정하고, 가장 중요한 정보를 먼저 전달하기
   • 하나의 문단 안에서는 하나의 내용만 다루는 것이 좋다

• 그 하나의 문단 안에서도 핵심 문장을 한 문장으로 정리한 후에, 그 뒤에 보충 문장들을 전개하기

수정 단계

• 초고를 작성한 다음, 퇴고하는 과정이 정말 정말 정말 중요하다!!
• 처음 분석한 독자가 바뀌지는 않았는지
• 독자가 필요한 내용을 쉽게 찾을 수 있도록 목차가 효과적으로 구성되어 있는지
• 독자가 필요로 할 정보를 놓치지는 않았는지
• 이해를 위해 예제나 시각적 자료를 추가한 경우, 이런 것들이 정말 도움이 되는지
  • 오히려 독자를 더 혼란스럽게 하지는 않는지!!
• 테크니컬 라이팅 원칙을 잘 준수했는지

테크니컬 라이팅의 네 가지 원칙

정확성

: 정확한 정보와 사실만 전달하기

• 기술적 오류 없이 정확한 정보를 전달하는가?
• 개념, 논리, 데이터의 해석이 정확하도록 작성하기
• 부정확한 정보는 차라리 삭제하기
• 주관적인 생각과 추측은 배제하기

명확성

: 내용의 모호함으로 독자를 헷갈리게 하지 않기

• 내용의 모호함 없이 한 번에 이해가 되는가?
• 중의적인 의미를 가지는 문장 피하기
• 대상을 생략하지 말고 명확히 표현하기, 대명사 사용을 자제하기
  • 앞에서 언급했던 대상이라 하더라도 그것, 이것 같은 대명사를 사용하는 대신, 반복이 되더라도 무엇인지 명확하게 한번 더 언급해주는 것이 좋다
• 수동형 문장 대신 능동형 문장을 사용하기
  • 업체 코드는 반드시 입력되어야 합니다 (X)
  • 반드시 업체 코드를 입력해야 합니다 (O)
• 사용자의 액션이 필요한 경우, 평서문 대신 명령문 사용하기
• 부정문 대신 긍정문을 사용하기 (순화!)
• 미래형 대신 현재형을 사용하기
  • 보기 버튼이 눌러지면 화면이 띄워질 것입니다 (X)
  • 보기 버튼을 누르면 화면이 나타납니다 (O)
• 주관적으로 해석될 수 있거나, 애매한 표현 사용을 피하기
  • 로딩 시간이 오래 걸리면 약간의 지연이 발생할 수 있습니다 (X)
  • 로딩 시간이 5초 이상 걸리면 화면에 지연 안내 메시지가 표시됩니다 (O)

간결성

: 이해하기 쉽도록 짧고 간결하게 쓰기

• 한 번에 이해되도록 문장이 간결한가?
• 수식어가 많거나 너무 긴 문장은 의미 단위로 나누기
  • 사용자는 계정을 등록할 때 반드시 이메일 주소와 비밀번호를 입력해야 하며, 입력된 정보는 데이터베이스에 저장된 후 사용자의 이메일로 인증 링크가 발송됩니다. (X)
  • 사용자는 계정을 등록할 때 이메일 주소와 비밀번호를 입력해야 합니다. 입력된 정보는 데이터베이스에 저장됩니다. 저장된 이메일로 인증 링크가 발송됩니다. (O)
• 핵심만 남기고 버리기, 불필요한 단어는 제거하기
  • 장황한 표현을 쓰지 말고, 글을 간결하게 유지하려 노력하기
• 장황한 서술형 문장은 목록화하기!!!
  • 순서 상관 없는 정보의 나열은 bulleted list (-, *, etc.)
    • 시스템 점검 시간에는 로그인, 결제, 고객센터 이용이 제한됩니다. (X)
    • 시스템 점검 시간에는 다음 기능을 이용할 수 없습니다. (O)
      • 로그인
      • 결제
      • 고객센터
  • 절차는 numbered list (1, 2, 3, ...), One action in One step!
    • 채널 개설 과정에서는 기본 정보만 입력받으므로 개설이 끝났다면 프로필 > 채널홈 설정에서 내 채널을 잘 알릴 수 있도록 정보를 꼼꼼히 입력하시고 프로필 > 프로필 설정에서 채널 공개 설정을 ON으로 변경해주세요. (X)
    • 아래처럼 수정할 수 있다:
      1. 채널 개설 시 기본 정보를 입력해 채널을 개설합니다.
      2. 개설 후에는 [프로필] > [채널홈 설정]에서 채널 정보를 추가로 입력합니다.
      3. [프로필] > [프로필 설정]에서 채널 공개 설정을 'ON'으로 변경합니다.

일관성

: 한 사람이 쓴 것 같은 느낌을 주도록 쓰기

• 한 사람이 쓴 느낌을 주는가?
• 어미를 다르게 사용한 경우 어미를 통일하기 -> 일관된 톤을 유지!
  • 설정을 저장합니다. / 설정이 완료됩니다. / 설정을 마쳐주세요. / 참고하세요. / 참고 바랍니다. / 참고해 주세요. / 참고합니다. (X)
  • 설정을 저장합니다. / 참고합니다. (O)
  • 유저가 로그인하면 access token이 발급됩니다
  • 발급된 토큰은 이용자의 요청을 처리할 때 사용되며,
  • 사용자는 설정 페이지에서 Token을 직접 확인할 수 있습니다.
  • user 인증에 실패하면 오류 메시지가 표시됩니다.
  • 사용자가 로그인하면 액세스 토큰이 발급됩니다.
  • 발급된 엑세스 토큰은 사용자의 요청을 처리할 때 사용되며,
  • 사용자는 설정 페이지에서 액세스 토큰을 직접 확인할 수 있습니다.
  • 사용자 인증에 실패하면 오류 메시지가 표시됩니다.
• 문서를 작성할 때, 영문을 풀어서 사용하는것보다는 한글로 바꿔서 작성하고, 필요하다면 괄호에 영문 표기를 병기하는 것이 좋다
• 서식이나 표기법도 일관된 기준을 사용하기 -> 스타일 가이드 활용
  • 'OK'를 클릭합니다. / [Ok]를 클릭합니다. / Ok를 클릭합니다. (X)
  • [Ok]를 클릭합니다. 로 통일
• 스타일 가이드?
  • Microsoft Manual of Style
  • The IBM Style Guide
  • The Chicago Manual of Style Online
  • Google developer documentation style guide
  • 카카오 개발자 문서 스타일 가이드

일관된 용어(공식 용어) 사용하기 -> 용어집 활용

주니어 개발자에게 해주고 싶은 이야기 (etc.)

상대방이 이해하지 못하는 것은 내 책임이다. 알아듣게 설명하자!!

• 커뮤니케이션의 핵심은 상대방을 이해시키고, 상대방과 동일한 내용으로 소통하는 것
• 나만 아는 용어를 사용하거나, 상대방의 이해도를 고려하지 않고 의사소통함으로써 의사소통이 어려워지는 경우가 종종 있다.
• 나만 하고자 하는 말을 한다고 끝이 아니라, 상대방이 이해하지 못하는 것은 나의 책임이라는 생각을 가지고 상대방을 위한 소통을 할 수 있도록 노력하기
• 협업 과정에서 기획자, 디자이너, 비 전공자 등과 소통할 일이 반드시 생길 것
  • 그런 사람들도 이해할 수 있도록 용어를 풀어 사용하거나, 어디까지를 알고 어디서부터 모르는지를 알고 커뮤니케이션하면 시간과 노력을 아낄 수 있을 것

개발자는 글을 못 쓴다?

• 글쓰기는 자전거 타기와 같다. 연습하면 나아진다!
  • 내가 글을 못 쓴다고 좌절하고, 내 영역이 아니라고 배척하지 말고, 꾸준히 연습하기
  • 글 쓰기 수업을 몇시간 듣는다고 한번에 변할 수는 없다.
  • 글을 쓸 때 어떤 것들을 파악하면 좋은지 신경쓰는 것만으로도 많이 성장할 수 있을 것
  • 하지만 직접 연습하고 적용해봐야지만 글쓰기 실력이 나아진다!

쉽게 설명할 수 없으면, 제대로 아는 것이 아니다 - 아인슈타인

• 간결하고 명확하게 쓸 수 없다면, 글쓰기 실력의 문제가 아니라 제대로 아는 것이 아닐 수 있다
• 배운 내용을 나의 것으로 만드려면, 쉽게 설명하는 연습!
  • 내가 아는것이 무엇인지, 맞는지 점검한 뒤에 글을 쓰는 것이 좋을 것

더 읽어보면 좋을 책

• 이공계 Technical Writing 가이드
• 개발자의 글쓰기
  • 개발자 입장에서 기술 보고서나 장애 보고서, 변수 네이밍과 관련된 글쓰기를 배워보려면 좋을 것
• Clean Code
• 개발자를 위한 글쓰기 가이드
  • 문장 단위의 글쓰기 기법들에 대해
• 어디에 적용할 수 있을까?
  • 사용자 가이드
  • 인수인계 가이드
  • 에러 메시지
    • 에러 메시지도 테크니컬 라이팅 기법을 적용할 수 있음!!
  • 업무 공유, 사내 메신저

질의응답

• 개인적으로 하나의 포스팅에 너무 많은 내용을 담기보다는, 포스팅을 나누는 것을 선호함
  • 하나의 페이지에 글이 너무 많이 있으면, 사람이 집중력이 떨어지게 됨
    • 읽다가 확 내려버릴 수 있음..
• 독자는 별로 궁금하지 않은데, TMI로 적는 경우가 많음
• 글을 작성할 때, 하나의 포스팅에 너무 많은 내용이 들어간다면:
  • 내가 이 글을 작성할 때 세운 독자가 궁금해 할 만한 내용이 무엇일까 생각
  • 내가 전달하고 싶던 핵심 메시지가 무엇일까 생각
  • + 별도의 포스팅을 작성하고, 링크로 처리해 주는 것도 방법이 될 수 있을 것