글또 - 기술블로그로 알아보는 테크니컬 라이팅

2023-12-155 min read

기술블로그로 알아보는 테크니컬 라이팅

테크니컬 라이팅의 개념과 문서 작성 프로세스

테크니컬 라이팅의 개념과 특징

특정 독자를 대상으로 특정 목적을 갖고 특정 정보를 전달하는 글쓰기
기술 정보를 명확하고 이해하기 쉽게 전달하는 글쓰기

매체가 다양해지면서 테크니컬 커뮤니케이션라고도 표현하기도 한다.

문학 글쓰기와 테크니컬 라이팅의 차이

문학 글쓰기

내용: 창의
대상: 일반
표현: 상징
구성: 자유

늘고마운
당신인데

바보처럼
짜증내요

- 하상욱 단편 시집 '알람' 중에서 -

테크니컬 라이팅

내용: 사실
대상: 특정인
표현: 직설
구성: 순차

알람은 다음을 가리키는 말이다.
자명종: 문제나 조건에 맞춰 경고를 주는 장치

글을 써야 하는 이유

효과적인 의사소통

정확하게 생각을 전달해 오해없이 소통하고 업무 효율을 높임

정보 기록과 보존

기억력의 한계를 보완
다른 사람에게 쉽게 전달 가능

경쟁력 강화

경험과 지식을 공유

글쓰기는 왜 어려운가

KM 올인원 관리 서비스는 사용자가
구매할 수 있는 모든 관리 서비스를 지칭하고,
서비스 종류에는 이벤트 모니터링 서비스,
알림 발송 서비스로 구성된다.

그냥 쓰는 것이 아닌 제대로 쓰는 것이 중요하다.

제대로 쓰지 않는 글로 소통하는 것은 더 많은 비용이 든다.

글쓰기도 기술, 연습하면 누구나 잘 쓸 수 있다.

Write to express, not to impress

인상을 주기 위해서가 아니라 표현하기 위해 쓴다.

개발자와 테크니컬 라이팅

개발자에게도 중요한 글쓰기, 문서화 능력
개발자가 접하게 되는 많은 기술 문서들

기술 문서 작성 프로세스

글쓰기 과정 3단계

작성 계획(Prewriting) - 소재를 찾고 일정을 계획
초안 작성(Drafting/Writing) - 자료 수집 & 배치
고치기(Revising/Editing) - 검토하기, 글 수정하기

독자를 선정하고 주제를 잡는 방법

누구에게 쓸 것인가, 독자 선정하기

타깃 독자층을 잡아놔야 한다.

독자들의 이해도에 따라 글 유형은 달라진다.

읽는 이가 누구인지 확실하게 정의하기

설명할 기술의 깊이를 조절한다.

구체적으로 대상 독자를 정하고 글을 쓴다.
독자에 맞게 전문용어를 사용하고 풀이를 제공한다.

무엇을 쓸 것인가, 주제 잡기

주제를 정한다.

주제는 글감이라고도 하며, 내용, 메시지, 테마 등이 함께 뒤섞인 말이다.

쓰고자 하면 모든 것이 쓸거리

소재는 많이 쌓여있다.
ex) 새 환경 적응기, 개선 사례, 작업 절차

쓸 주제가 없는게 아니라 주제를 정하지 못한 것뿐

주제를 정할 때 생각할 점

작성자와 독자 모두 관심이 있는가
자료를 충분히 찾을 수 있는가
일정 내에 쓸 수 있는, 너무 방대하지 않은 주제를 정하라

한 편의 글을 일정 내 좋은 품질로 완성하려면 주제를 좁히는 것이 중요하다.

저자가 잘 아는 주제를 정한다.

나만의 이야기를 전달하는 것이 중요하다.

어떻게 시작할까, 소재 모으기

자료가 반이다.

필요한 자료를 찾고야 말겠다는 다짐을 유지하며 각성한 상태로 찾는다.

필요한 자료만 계획해서 찾아내는 것이 중요하다.
소재를 꾸준히 모아두는 것이 중요하다.
날짜, 출처 기입 또한 매우 중요하다.
정해진 한 군데에만 메모해 두는 것이 중요하다.

왜? 에 대한 답을 찾는다.

구체적인 근거와 사례가 필요하다.
주장 및 설명할 때는 이유, 사례, 데이터를 정확히 표기해두어야 한다.

초안 작성하기

일단 쓴다

자신에게 맞는 글쓰기 방법을 사용하는 것이 중요하다.

세부 목차를 꼼꼼하게 잡고 1페이지부터 쓴다.
어디서부터든 일단 쓴다.

그래도 자신 있는 부분부터 일단 쓰면 포기할 확률이 낮아진다.

맨 처음에는 글의 키워드부터 정하면 좋다.

키워드 > 문장 > 단락 > 챕터 > 문서

Clear 명확성
Concise 간결성
Consistent 일관성

명확하게 쓴다

명확하다는 것은 오해를 불러 일으키지 않는 글이다.

모호함이 없고 확실하게 쓴다.
정확한 내용으로 선명한 문장을 사용한다.
명확하게 표현한다.
모호하지 않게 숫자로 표현한다.
객관적으로 데이터를 표기한다.
분명한 글꼬리를 사용한다.
대명사는 되도록 쓰지 않는다.
링크 이름을 대명사로 쓰지 않는다.

간결하게 쓴다

간결하다는 것은

간단하고 깔끔하다.
짧고 쉽다.

단문으로 짧게 쓰는 것이 리듬감있고 읽기 편하다.

쉬운 표현으로 한자어보다는 쉬운 우리말을 쓰는 것이 좋다.

말하듯 쓰면 된다.

일관되게 쓴다

내용, 형식, 표현을 일관되게 사용한다.

문서 주제의 일관성을 유지해야 한다.

같은 주제를 나타내고 있는지 항상 확인하는 것이 중요하다.

형식도 일관성을 유지해야 한다.

명사형으로 끝낼지, 완전한 문장으로 끝낼지 염두에 두어야 한다.

용어나 표현을 일관되게 사용한다.

일관되지 않으면 독자가 혼란에 빠진다.

쓸 용어를 미리 정해 두면 좋다.

문서 고치기

검토와 재작성의 중요성

글쓰기의 본질은 고치기

전체적으로 다시 검토
글을 객관적으로 검토하기 위해 시간 간격을 두고 검토
예비 독자에게 피드백을 요청해도 좋음

문서 구조 검토

빠짐없이 완전하게
핵심 내용부터 소개

MECE - 빠진 내용을 찾기에 좋은 기법

Mutually exclusive collectively exhaustive

목차를 정하는 것도 좋은 방법이다.
예상 독자나 주제 범위를 미리 조정해도 좋다.
목차 제목도 적절하게 나타낼 필요가 있다.

문장 검토하기

바른 문장을 쓰자.

불필요한 단어는 삭제하자.

문장의 기본 골격
- 주어구 + 서술어구

구성 요소의 호응
- 주어와 서술어가 호응해야 한다.
- 목적어와 서술어가 호응해야 한다.
- 부사어와 서술어가 호응해야 한다.

불필요한 말과 조사를 붙이지 않는다.
문장은 줄이고 줄여서 간결하게 쓰자.
외국어보다 우리말을 사용한다.
은어 사용에 주의한다.
구어체를 다듬는다.

전문용어와 약어 풀이 추가

용어 정의하자.

특정한 개념으로 정의된 단어
절대적인 의미

약어 풀이하자.

가독성 높이는 법: 단락 다시 쓰기

단락 쓰기

너무 길면 지루하다.
단락 하나에 중심 생각 하나만 담는다.
아이디어나 주제에 따라 단락을 나눈다.

점 목록 - 순서에 상관없이
숫자 목록 - 순서가 있는

가독성 높이는 법: 시각 자료 활용하기

시각적 자료를 먼저 보고 인지한다.

스크린 숏 사용

필요한 부분만 캡처
강조 표시 활용
설명 텍스트는 이미지 바깥에 배치

가독성 높이는 법: 표 사용하기

방대한 양의 데이터 사용하거나 상세한 비교가 필요할 때 사용하자.

맞춤법과 외래어 표기법 확인하기

헷갈리면 검색하자..!

도입부 작성하기

도입부의 역할

글을 읽을 동기 부여
흥미 유발
본문 안내

다음과 같이 시작할 수 있다.

질문으로 시작
용어나 개념 정리
경험
인용
요즘 화젯거리

개요를 추가하는 것도 좋다.

글을 쓴 배경
글에서 다루는 주제
대상 독자
글을 읽고 독자가 알 수 있는 것
글에서 다루지 않는 것

제목 짓기

요점을 담는다.
의미를 명확하게 전달할 수 있어야 한다.
내용에 맞는 제목으로 정한다.

동료 검토와 문서 배포하기

동료 검토

효율적인 자기 검토 방법

객관화 ex) 하루가 지난 후에 읽기
다른 감각 활용하기 ex) 소리내어 읽기
매체 변경하기 ex) 인쇄해서 읽기

동료 검토의 목적은 서로의 글을 읽으면서 분석적 읽기를 연습하고 자신의 글을 되돌아본다.

문서 배포하기

최종 점검

기밀 정보 확인
최신 정보인지 확인
시각 자료 확인
코드 확인
링크 테스트
출처 확인
문서 스타일 일관성 확인

일단 글쓰기를 시도해 보는 것이 가장 중요하다.

연습하지 않고는 잘 쓸 수 없다.

꾸준히 글쓰기 근육을 만들어야 한다.

정리

테크니컬 라이팅 개념과 특징
작성 계획
초안 작성 (명확, 간결, 일관)
고치기 (문서 구조 확인, 가독성 높이기)
동료 검토