테크니컬 라이팅 세미나 정리/후기

2024-03-09 21:22:00

Reading time ~8 minutes

📌 테크니컬 라이팅 세미나 후기

테크니컬 라이팅 세미나를 다녀왔다

닷넷데브에서 무료로 테크니컬 라이팅 세미나를 연다고 소식을 듣게 되어서 퇴근 후 뚝섬까지 다녀왔다.
발표자는 닷넷데브를 운영 중이신 남정현님이셨고, 얼마 전 .NET Conf 2024에 다녀온 터라 살짝 내적 친밀감이 있었다. (나만)
아마 저녁 7시 반에 시작했던 것 같은데 시간이 빠듯해서 저녁도 못먹고 부랴부랴 가서 노트북 키고 열심히 재밌게 듣고 왔다.
작년부터 회사에서 Notion을 도입했는데 도입하면서 문서화할 일이 많았고 그 경험을 가지고 들으면서 여러 개선점을 찾을 수 있었다.
장소는 튜링의 사과였는데 여기가 주 고객층을 개발자로 타겟팅하는 스터디카페 같은 느낌이다.
시설도 좋고 개발자스러운(?) 장소라서 마음에 들었다.

발표자 및 참관 세미나 정보

발표자 - 남정현님
남정현 - MEGAZONECLOUD | LinkedIn

참관 세미나 정보
『튜링의 사과』 Original Lecture Series PART2 ‘개발자의 글쓰기’ (velog.io)

듣고 나서 주말에 강의 시간에 배운 내용을 복습할 겸, 강의 내용을 떠올리며 요약해봤다.
물론 이 내용도 나름 강의 때 배운 스킬?을 적극 활용하여 쓸려고 노력했는데 잘 됐는지 모르겠다.

1. 테크니컬 라이팅의 중요성

기업의 3대 부채

기업의 부채에는 여러 종류가 있겠지만, 대표적으로 아래와 같은 것들이 있습니다.

투자금: 사업을 확장하기 위해 투자자로부터 받은 자원. 언젠가 갚아야 할 자금.
기술부채: 장기적인 관점에서 언젠가 처리해야 할 기술적인 문제.
지식부채: ?

지식의 부채는 무엇일까요?

기업 입장에서 지식의 부채란, 기업의 프로젝트에 대해 과거 히스토리 추적이 불가능하여 언젠가 다시 추적해야 할 지식의 공백을 뜻합니다. 이는 프로젝트에 국한된 내용은 아닙니다. 특정한 업무 프로세스나 시설의 유지/관리 등, 히스토리 관리가 필요한 모든 영역에 해당되는 내용입니다.

그리고 이러한 지식의 부채를 최소화하기 위한 방법 중 가장 효과적인 방법은 문서화입니다. 히스토리를 파악하는 가장 좋은 방법은 잘 정리된 문서를 보는 것만큼 효율적인 방법은 없으니까요. 그러한 관점에서 테크니컬 라이팅은 문서화를 하는데 큰 도움을 줄 수 있습니다.

테크니컬 라이팅이란, 좁은 의미로는 과학 기술 정보를 정확하고 효과적으로 전달하기 위한 문서 작성 기술을 뜻하지만, 넓은 의미로는 단순히 과학 기술 정보를 정확하게 전달하기 글쓰기를 일컫는 것 뿐만이 아닌, 모든 유형의 글을 보다 분명하고 알기 쉽게 전달하는 글쓰기를 통칭합니다.

문서화가 중요한 곳은 기업에만 해당할까?

그렇다면 문서화가 필요한 곳은 기업에만 해당할까요? 꼭 그렇지만은 않습니다.

오픈소스 라이브러리를 예로 들어보겠습니다. 오픈소스 라이브러리란 무료로 사용할 수 있는 소프트웨어 구성 요소로, 소스 코드가 공개되어 있고 누구나 해당 소프트웨어를 자유롭게 사용하고 수정할 수 있습니다. 아래는 유명한 오픈소스 중 하나인 Node.js 오픈소스 링크입니다. nodejs/node: Node.js JavaScript runtime ✨🐢🚀✨ (github.com) 스크롤을 조금 내려보면 프로젝트에 대한 개요, 설치 방법 등이 작성되어 있고 공식 홈페이지에서는 사용 예제, API 문서 등이 상세히 작성되어 있습니다. 프로젝트에 대한 문서화는 오픈소스를 더 좋은 방향으로 수정하는 기여자에게 도움이 될 수 있습니다.

또한, 프로젝트를 사용하는 사용자의 입장에서도 더욱 쉽게 사용할 수 있는 참고자료가 됩니다. 기여자와 사용자의 참여가 늘어날수록, 집단 지성으로 인해 프로젝트가 더 좋은 방향으로 나아갈 수 있게 됩니다. 만약 아무리 좋은 기능이 구현된 라이브러리라도, 위의 예시처럼 프로젝트에 대한 문서화가 안 되어 있었더라면 과연 많은 기여자와 사용자를 얻을 수 있을까요? 아닙니다. 사용자의 입장에서 좋은 기능이 구현되었다고 해도, 문서화가 되어 있지 않으면 해당 기능을 제대로 활용할 수 없습니다.

문서화된 정보 없이는 프로젝트의 설치 방법, 사용 방법, API 사용 방법 등을 파악하기 어렵기 때문에 사용자들은 프로젝트를 활용하는 데에 어려움을 겪게 됩니다. 사용자가 줄어든다면 기여자 또한 줄어들 것이고, 그렇게 된다면 아무리 좋은 라이브러리라도 Node.js처럼 발전하기 힘들 것입니다. 단편적인 예로 오픈소스 라이브러리를 들었지만, 기술 블로그나 학술 논문, 계약서 등, 문서화는 모든 분야와 영역에서 중요합니다.

2. 테크니컬 라이팅을 위한 3단계 접근법

그렇다면 테크니컬 라이팅을 잘 하기 위해 필요한 3단계 접근법을 배워보도록 하겠습니다.

※ 3단계 접근법
1) 누구를 위한 가이드인가?
2) 읽는 사람이 어떤 내용을 알 수 있는가?
3) 읽는 사람이 이 가이드를 읽으면서 어떤 어려움을 만날 수 있는가?

1단계. 누구를 위한 가이드인가? (독자 분석)

작성하고 있는 문서가 어떤 사람이 필요로 하는 지를 아는 것이 중요합니다. 이를 ‘페르소나 분석’이라고 합니다. 페르소나 분석이 중요한 이유는 읽는 사람에 따라 각자의 이해수준이 다르기 때문입니다. 어떤 문서가 개발자에게 주로 읽혀지는지, 마케터에게 주로 읽혀지는 지에 따라 용어의 선택이나 내용을 차별적으로 작성해야 합니다. 독자의 이해수준 범위를 너무 넓게 잡는다면 모두를 이해시키는데 어려움이 있을 수 있습니다. 따라서 필요한 선수지식을 스펙으로 문서에 정리해두는 것 또한 큰 도움이 될 수 있습니다.

2단계. 읽는 사람이 어떤 내용을 알 수 있는가? (행위 분석)

독자가 어떤 내용을 궁금해 할 지, 어떤 행동을 취할 지에 대해 분석해야 합니다. 예를 들어, 사내에서만 내부적으로 사용하는 휴대폰 앱에 대한 메뉴얼을 작성한다고 가정해보겠습니다. 사내에서 사용하는 앱의 경우, 보통 앱스토어에 직접 올리지 않고 파일을 직접 다운로드하여 설치하는 방식을 채택합니다. IOS의 경우에는 이 과정이 안드로이드보다 복잡합니다. TestFlight 앱에서 따로 피드를 다운로드하는 방식으로 설치할 수 있습니다. 따라서 설치 과정부터 안드로이드와 IOS의 메뉴얼을 디테일하게 나눌 필요가 있습니다. 독자의 행위를 분석하면서 다양한 상황을 고려하여 문서화를 한다면, 독자로 하여금 유용하고 필요한 정보를 제공할 수 있습니다.

3단계. 읽는 사람이 이 가이드를 읽으면서 어떤 어려움을 만날 수 있는가? (문제점 분석)

문서를 아무리 잘 작성하더라도, 따라하는 사람들로 하여금 여려움을 만날 수 있습니다. 가령, ‘A와 B라는 단계를 거치면 C가 됩니다.’라는 내용을 서술했지만, 사용자가 직접 진행해보니 ‘A와 B라는 단계를 거쳐 D가 되었습니다..?’와 같은 상황이 발생할 수 있다는 것 입니다. 이러한 상황에 대해 어떤 문제점이 있고 해결 방법은 무엇인지 오류 케이스를 정의한다면 독자에게 큰 도움이 될 것 입니다.

3. 테크니컬 라이팅을 위한 5가지 연습법

테크니컬 라이팅을 위한 5가지 연습법을 알아보겠습니다.

※ 5가지 연습법
1) 좋은 표현 많이 익히기
2) 비문학적 글쓰기
3) 일관성 있는 글쓰기
4) 글을 테스트하는 방법
5) 글쓰기를 넘어서는 정보전달

첫 번째, 좋은 표현 많이 익히기

좋은 표현을 많이 익히는 것은 글쓰기에 큰 도움이 됩니다. 내가 전달하고자 하는 의미를 적절한 단어를 사용하여 전달하는 것이 가장 간단명료하기 때문입니다. 그렇다고 특정 기술이나 단어를 시간내서 공부할 필요까지는 없습니다. 물론 공부한다면 좋겠지만, 내가 관심있는 분야에 대한 다른 사람들의 글을 많이 접하고 텍스트와 친해지는 것으로 충분합니다.

두 번째, 비문학적 글쓰기

대부분의 문서화는 예술적 목적이 아닌 정보전달의 목적을 가지는 비문학적 글쓰기 방식이 채택됩니다. 아래는 비문학적 글쓰기에 중요한 다섯 가지 내용입니다.

날짜와 시점을 명확히하고, 추측이 아닌 숫자와 데이터를 근거로 서술하자. 예를들어, ‘현재 스트라이크 존의 크기는 홈플레이트의 크기인 43.18cm이므로, 43.18cm로 구현합니다.’라는 내용이 2020년에 문서화 되었다고 가정합시다. 그러나 2024년 기준 스트라이크 존의 크기는 홈플레이트의 양쪽 +2cm가 적용되어 47.18cm가 되었습니다.

독자가 2024년 이후에 예시의 문서를 읽게 된다면 ‘현재’라는 부분을 보고 2024년에도 홈플레이트의 크기는 여전히 43.18cm라고 착각할 수 있습니다. 때문에 날짜와 시점에 대한 부분은 명확한 표현으로 작성하는 것이 좋습니다.

또한 추측이 아닌 숫자와 데이터를 근거로 글을 작성해야 정보전달의 효율성과 신뢰성을 더할 수 있습니다.

사물의 상태 변화를 쓸 때만 수동태로 표현하고, 평소에는 능동태로 명확하게 표현하자. 수동태: 유격수가 1루에 송구하여 타자가 아웃 되었습니다. (아웃으로의 상태변화) 능동태: 지금 그라운드는 만루 상태 입니다.

비문학적 글쓰기에서 수동태로 표현해야 할 것은 상태변화 이외에는 거의 없습니다. 상태변화 외에는 능동태로 명확하게 표현하는 것이 간결하고 효율적으로 읽히기 쉽습니다.

의도가 변하지 않고 말이 된다면 핵심 문장 성분만 남기자. 글을 쓰다 보면 본인도 모르게 글이 부풀려지는 현상을 경험하실 수 있습니다. 그럴 때는 과감하게 필요 없는 부분을 지우고 핵심적인 단어로 구성한다면 명확하게 표현할 수 있습니다.
한자어, 외래어, 영어, 전문 용어는 필요할 때만 사용하고 번역체는 멀리하자. 우리나라 말로 충분히 표현 가능한 경우, 우리말을 사용하는 것이 여러 독자가 접근하기에 좋습니다. 그리고 3단계 접근에서와 같이, 읽는 사람의 테크 레벨을 고려하여 전문 용어를 사용하는 것이 좋습니다.
문단 하나에 세 문장 이하로, 한 가지라도 확실히 전하자. 한 문단에 하나의 의도를 가지고 쓰는 것이 좋습니다. 표현하고자 하는 내용이 많아진다면 하나의 문단도, 그 안의 문장도 읽기 힘든 내용으로 쓰여질 수 있습니다.

세 번째, 일관성 있는 글쓰기

일관성 있는 글쓰기는 무엇일까요? 글의 스타일을 일관되게 유지하는 것 입니다. 글의 규격만 스타일이 아닙니다. 글에서 어떤 단어를 쓰는지, 어떤 느낌의 문장을 쓰는 지도 하나의 스타일이 될 수 있습니다.

애플 스타일 가이드
https://support.apple.com/ko-kr/guide/applestyleguide/welcome/web

마이크로소프트 스타일 가이드
https://learn.microsoft.com/ko-kr/teamblog/style-guide

각 기업에서 사용하는 문서 작성 스타일 가이드 입니다. 마이크로소프트의 스타일 가이드는 문서화의 정석적인 스타일을 지향한다면, 애플의 스타일 가이드는 읽는 사람들로 하여금 애플스러운 감성을 느끼게 하기 위한 스타일을 지향하는 느낌을 받을 수 있습니다. 위의 예시처럼 글의 스타일 또한 독자의 유형에 따라 달라질 수 있겠죠?

네 번째, 글을 테스트하는 방법

잘 쓴 글이라도 정말 잘 쓰여진 글인지 테스트하는 과정이 필요합니다. 테스트 하는 방법은 여러가지가 있습니다.

글을 쓸 때는 집중하고, 읽을 때는 편하게 읽는다.
다 쓴 글에 대해 리뷰를 받는다. 리뷰를 해준 이에게 답례는 잊지 말자. 타인에게 글에 대한 리뷰를 받는 것은 유효한 테스트 방법입니다. 글쓴이는 글을 쓰는 과정에서 글의 내용과 구조가 익혀진 상태인 반면, 글을 처음 읽는 사람은 아예 처음 접하는 내용이기 때문입니다.
장소를 바꾸는 등 환경을 다르게 하여 읽자. 환경을 다르게 하여 읽는다면, 글을 쓰는 당시의 상태와 받아드리는 정보에서 차이가 있을 수 있습니다. 가끔은 야외에서 읽어보기도 하고, 카페에서 읽어보기도 하는 등 여러 장소나 환경에서 읽어볼 수 있도록 하는 것이 좋습니다.
스마트폰으로 읽어보기도 하고 인쇄하여 읽어보기도 하자. 화면의 크기가 다른 디바이스로 글을 보게 되면 문단 구조가 의도했던 것과 달라질 수 있습니다. 그리고 문단 구조에 따라 우리의 뇌는 글을 다르게 읽을 수 있습니다. 따라서 문단 구조가 달라질 때, 어떤 식으로 읽히는지 파악하는 것도 도움이 될 수 있습니다.
텍스트 확대 배율을 다르게 하여 읽어보자. 디바이스 크기와 비슷한 내용입니다.
글을 고쳐야 한다면 어떻게 고쳐야하는가? 타당성적인 측면에서 형식적인 부분에서 완성도를 챙기는 것이 중요합니다.
사실과 데이터 기반, 객관성을 근거로 쓰자.
우리가 쓰는 글이 비문학이라는 점을 인지할 것.

맞춤법을 검사하는 것은 기본입니다.

최소한 기본적으로 글을 다 쓰고 나면 맞춤법 검사를 돌려볼 것.
평소 글을 작성할 때 뜨는 빨간 밑줄을 무시하지 말 것.

다섯 번째, 글쓰기를 넘어서는 정보전달

글만 잘 쓰기만 하면 잘 전달 될까요? 그럴 수도 있겠지만, 글 외적의 요소에도 신경쓴다면 더욱 좋은 글이 탄생할 수 있습니다.

정보전달의 수단

이미지
비디오
오디오
인터랙티브 데모
다이어그램

정보를 잘 전달하기 위해 고려할 것

디자인, 타이포그래피, 접근성, 가독성
문단 배치, 들여쓰기/내어쓰기

위의 예시처럼 글뿐만 아니라, 이미지나 비디오 등 여러 시청각 자료를 통하여 정보를 전달한다면 독자가 더욱 이해하기 수월해질 수 있습니다. 또한, 여러 방면에서 글 외적의 요소를 신경쓴다면 가독성 있는, 읽히기 쉬운, 독자를 배려한 글을 쓸 수 있겠죠?

후기

나는 글쓰기 자체를 좋아하지만 글 쓰는 시간이 오래 걸리는 편이다.
문서화도 마찬가지.. 프로젝트에 대한 내용을 문서화하는 것도 생각보다 많은 시간을 쏟는 경우가 허다했다.
그런 입장에서 단계별 접근법은 큰 도움이 됐다.
그리고 무언가에 대해 글을 쓸 때, 좋은 글을 쓰기 위한 방법을 고민은 해봤지만 강의 내용처럼 그 방법에 대해 깊이 생각한 적은 없었다.
그래서 내가 글을 쓸 때, 인지하지 못한 부분에 있어서 큰 도움을 받았다.
앞으로 블로그에 개발 관련 글을 쓸 때도 큰 도움이 될 것 같아서 시간이 아깝지 않은 세미나였다.
굿굿 ^ㅁ^b