[Ncloud] Technical Writer 팀 특강 후기: 신뢰를 주는 기술 글쓰기

 

 

 

 

 

글을 잘 쓰는 방법에 대해 늘 고민이던 차에, 좋은 기회를 얻어 네이버클라우드 테크니컬 라이팅 팀 리더분의 특강을 듣게 되었습니다.

 

정리하여 공유해보겠습니다.

 

 

가장 중요한 점은 기술 문서를 쓸 때에는 내 나름대로 작성하는 것이 아니라, 정확한 내용을 담는다는 점입니다.

 

목차
Introduction
- Technical Writing 정의
- 강의 목표와 기대 효과
Easy to Find: 찾기 쉬운 문서 만들기
- 정보 구조화
- 검색 최적화
Easy to Understand: 이해하기 쉬운 문서 작성
- 사용자 분석
- Plain Language 원칙
- 시각 자료 활용
Easy to Use: 활용하기 쉬운 문서 설계
- 문제 해결을 위한 문서 설계
- 행동 중심의 내용 구성

 

효과적인 테크니컬 라이팅 원리: 찾기, 이해, 사용

 

시작은 문학적 글쓰기와 차이로 문을 열었습니다.

1. 문학적 글쓰기 : 표현력, 감성, 아름다움으로 읽는 즐거움을 느끼고, 저자의 개성을 강조합니다.
2. 기술 문서 : 객관적 사실을 명확히 작성하고, 사용자의 작업을 유도합니다. 정확성, 명확성, 구조화 > 문제 해결 > 일관성과 표준화가 되어야 합니다.

 

테크니컬 라이팅의 3대 원칙

테크니컬 라이팅의 3대 원칙은 "쉽게 찾고, 이해하고, 사용한다." 라는 점을 두고, 하나씩 살펴보겠습니다.

 

쉽게 찾는다 : Easy to Find

 

정보 구조화

• 사용자가 원하는 정보를 빠르게 찾고, 문맥을 이해하기 쉽게 정보를 배열합니다.
• 분류하고 구조화합니다.

1. 중요한 것부터 보여준다
2. 사용자가 필요로 하는 순서대로 구성한다
3. 기본부터 응용으로 구성한다

 

Topic 단위의 구성

• 정보를 구성하는 방법입니다.
• 토픽 (문서의 의미 단위)을 쪼개어 작성한다.
• 청크를 의미 단위인 토픽이라고 한다.

 

기술문서의 토픽 세가지 : Concept Task Reference

1. 컨셉: 이게 무엇인가에 대한 정보를 준다.
2. Task: 절차, 조작 순서 나타냄. 123… 사용 순서 잘 넣어야 한다.
3. Reference : 항목, 세부정보, 매개변수, 에러코드 배치 등 테이블 형태로 모아서 한번에 부가정보를 줍니다.

 

 

정보 탐색 구조 설계

• 네비게이션? 검색?
• 정보 탐색하기 쉽게 하려고 예측한다.
• 전체 목차를 제공해서, 문서 구조를 한 눈에 바라본다.
• 브래드 크롬 : 실제 문서의 경로 정보
• 맨 아래 [이전], [다음] 정보가 어떤지 네비게이션으로 설계한다.
  • 블로그는 이 정보가 고정된 경우가 많다.
• 위키 페이지

 

검색 최적화 방법 3가지

• 검색 엔진에 내 문서가 잘 걸리게 해야 한다.

1. 메타데이터 활용
2. 키워드 최적화
3. 태그

 

* 메타데이터는 사람이 보려는 게 아닙니다.

검색 엔진에게 내 문서가 이렇다고 제공한다. 이런 태그에 매핑되는 검색되게 하는 문서 제공한다. 

문서 속성(제목, 설명, 작성자, 서비스명, 버전, 플랫폼 등)

 

* 키워드 최적화: 일반 사용자 타겟

자연스러운 키워드 반영하고, 동일 개념은 대표 용어 1개만 지정합니다.

즉, 같은 의미는 하나의 용어만 사용합니다. 이게 검색 최적화. 키워드 최적화라고 부르는 것입니다.

 

 

 

태그 관리 전략

• 사용자 타겟 태그 지정
• 키워드는 딱 대표 용어 하나만 지정해서 쓴다.
• 근데 대표 용어만 하면 안걸리자나. 그래서 로그인, Sign in, 인증 등 다 집어넣기.
• 대신, 동의어/약어도 확장 가능.
• 주의할 점: 검색엔진은 ‘띄어쓰기, 대소문자’에 민감합니다.

 

Easy to Understand

• 독자 분석
• 일관성 확보의 핵심 - 스타일 가이드
• Plain Language 원칙
• 이해를 돕는 시각 자료 활용

 

독자 분석

• 문서를 쓸 때, 독자를 분석하는 게 구조화에서 필요하다. 내용 전개시에도 중요하다.
• 독자의 배경지식
• 컨텐츠
• 어떤 맥락?

사용자 대상별로 설명 방식에 차이를 둡니다.

• 초급 사용자 : 기본 용어로 쉽게 설명합니다.
• 중급 사용자 : 너무 자세한 개념 설명보다, 절차 설명을 먼저 합니다.
• 전문가 : 예외사항, 활용 예제 위주로 꾸미는 것으로도 설명 가능합니다.

 

목적에 따라서도 구분할 수 있습니다.

• 네이버클라우드 기술 문서라면, 네이버클라우드 사용자가 이해하기 쉽게 만들어야 합니다.
• 블로그라면, 내 블로그를 누가 들어와서 볼지를 생각해보고, 블로그 작성 목적을 세웁니다.

 

일관성 확보의 핵심 - 스타일 가이드

이거는 다수가 함께 작성시 이 스타일 가이드 굉장히 중요합니다. 문서 일관성 통해 가독성, 신뢰도, 이해도 높이는 최소한의 장치로,

용어 일관성, 문법과 포맷의 문체 일관성을 고려합니다.

문서의 일관성 확보하여, 사용자를 고민하지 않게 만들어야 합니다.

 

 

패턴 정의

용어, 단어, 날짜표기 > 규칙을 정의한다.

문체 (톤 앤 매너) 통일을 위한 규정을 한다.

기술 글쓰기를 하려면, 가장 기본적인 내용에 충실한다.

 

토픽 (Topic)

1. 스타일 가이드 - 제목
2. 스타일 가이드 - 도입문

 

숙지하면 말할 수 있다. 이걸 도입문으로 작성할 수 있다. 기대하는 정보라 생각하고 들어가거나 바로 나아감. 제모과 사용자를 이어준다.

 

스타일 가이드 - 목록

• 순서가 없는 목록
• 순서가 있는 목록
• 물론 시나리오 같은 흐름은 쓰지만, 순서 기호 일반적으로 쓰지 않는다.

 

스타일 가이드 - UI 표기 규칙

• 웹 서비스 사용 
• UI 원문(실제 화면 텍스트)과의 일치성 유지
• 중요한거, 계속 화면 UI가 바뀔 수 있다.

 

일반 텍스트, GUI 텍스트 볼드체 표기하며, 네클가이드에서 볼드체는 GUI만 있다.

어느게 GUI, 버튼인지 바로 확인할 수 있다. [확인], <확인>, 확인 안된다. >> 하나로 통일하시라

네클 예시로 표기한다. 굵은 글씨 쓰고, 각괄호를 사용합니다.

 

스타일 가이드 - 표

• 내용 전개시 사용하는 도입글, 순서 목록 등 > 그 다음으로 많이 쓰는 게 “표” 입니다.
• 표에도 작성할 때, 스타일 가이드에 맞추어 주의해서 작성합니다.

표는 텍스트 공간 제약있습니다. 그래서 명사형으로 쓰는 것을 권유합니다.

조사도 생략, 다듬어서 명사형 쓰는게 문서가 더 깔끔하고, 가독성이 좋아집니다.

또한, 순서가 있어야 합니다.

 

제목

도입문

조작순서

 

GUI는 볼드체로 넣어주면, 아주 확연히 다르게 보인다.

* Plain Language 원칙: 간단하고 짧은 문장

 

 

Easy to Use

문제 해결을 위한 문서 설계

사용자가 스스로 문제 해결하도록 돕는 구조로, 기능 중심보다 문제 해결 중심으로 작성합니다.

특히, 도입문 만으로 내게 맞는 정보라는 점을 알 수 있어야 합니다.

 

기술 문서 전반에 걸쳐 문제 해결 목적 의식을 갖추어야합니다. 특히, Troubleshooting, FAQ, Error Message Guide에서 문제 해결 목적에 맞게 작성하는 것이 중요합니다. 

 

문서와 장애를 원인, 실질적인 원인 해결방법, 동일한 레퍼런스 하나 더 제공한다. > 알림 메시지 목록에서도 확인할 수 있다.

에러 해결의 상호 참조 하이퍼링크도 제공한다.

 

비교: FAQ

일반가이드와 다르게 자주 묶는 질문을 모아서 처리한다. 여기는 아주 자세한 해결 안함. 간단한거 모아서 답변한다.

FAQ는 가이드가 아니다. 혹은 필요시 상호 참조 링크를 보내어 상호 참조 가능하게 해주면 끝이다.

 

사용자 중심, 행동 중심 문장 설계

사용자가 직접 수행할 수 있는 행동 단위로 단계 제시

조작 지시문(능동문)

조작 결과문(피동문)

 

 

숫자는 조작 지시에서 많이 사용한다. 불필요하게 숫자 목록을 쓰지 않습니다.

피동문은 조작 결과 화면을 설명할 때 많이 사용합니다.

 

ex) 1. 점 목록은 조작 결과문(- 대시)

1. 접속해 주십시오


2. 로그인 버튼 클릭
 + 결과 화면 제시

 

신뢰를 설계하는 문서 작성 (1)

가장 최신 버전이라는 것을 심리적으로 인지시킵니다.

제품 스펙 정보, 수치, 단위에 오탈자가 있으면 안됩니다. 이런 경우 쓸모있는 정보로 안봅니다.

 

신뢰를 설계하는 문서 작성 (2)

특정 릴리즈를 한다.

애매한 것을 정확하게 만들어야 한다.

 

 

끊김 없는 정보 흐름 설계

내비게이션 요소 설계 원칙을 지킵니다. 특히, 사용자가 노력안해도 자연스럽게 찾게 해야 합니다.

 

이와 관련된 특성 네가지 기억합니다.

예측 가능성, 일관성, 가시성, 맥락 유지성

1. 예측 가능성
2. 일관성
3. 가시성: 어디든 눈에 띈다
4. 맥락 유지성: 맥락 정보를 어디든 유지하게 만든다.

 

찾기 쉽게 노출하고, 이해하기, 따라하기 어렵지 않은지, 문제가 해결될 수 있는지를 고민하며 작성합니다.

 

기술 문서를 사용할 때 주의사항에 대해 깊이 고민할 수 있는 시간이었습니다.

 

 

Easy to find, understand, use 원칙에 입각해서, 기술 문서를 작성한다는 점을 기억하고, 블로그 쓸 때도 유용한 정보를 일부 가져와서 적용해보겠습니다.