업무적 글쓰기가 고민인 당신을 위하여 - 개발자의 글쓰기

튜링의사과 Original Lecture (opens in a new tab) @튜링의사과
일시 : 2023년 2월 29일(목) 19:30
발표자 : 남정현 (Blog (opens in a new tab))
발표자료 : 발표자료 (opens in a new tab)

Overview

문서화를 왜 하냐? 모든 사람들의 시간이 소중하기 때문에.

발표자 소개

개발자로서 15년 넘게 계속 일을 해오고 있는데, 계속 도전 중이다
문서화의 중요성을 느껴서 테크니컬 라이터로 3년간 일했고, 지금도 계속 문서화에 많은 시간을 투자하는 중
현재 네이버 TCN 카페 운영진으로 활동 중

불편한, 하지만 마주해야하는 진실

비즈니스를 하면서 발생하는 3가지 부채

투자금 : 실제로 비즈니스를 하면 돈이 필요하니까 부채가 생긴다
기술 : 뭔가 시제품이나 이런걸 만들어내려고 엄청나게 빠르게 개발하다보니 주먹구구식으로 하기도 하고... 그렇게 해서 성공했다! 그러면 성공 이후는...?
지식 : 옛날에 뭔 짓을 해놨길래 이렇게 됐지? 이런 것들

만약에 문서화를 계속 등한시한다면?

-> 구전 주도 개발이 된다 (문서로 남기지 않고 말로만 설명하는 것). 아무도 모르는 히스토리가 저~ 멀리 쌓이게 되고, 나중에 내가 받아보는 지식은 아주 outdated되거나 쓸모없는 정보만 오게 된다.

오늘 얘기하고자하는 숫자

3과 5

3 -> 기술문서 완성을 위한 3가지 접근법
5 -> 기술문서를 잘 쓰기 위한 5가지 연습 포인트

기술 문서 뼈대 잡기 3단계

가상의 시나리오를 하나 생각해보자

어떤 회사가 사내 복지를 위해서 사내 카페를 운영하고 있었다. 원래는 손님 - 바리스타가 있고 그냥 커피를 시켜서 마시고 했는데 회사가 커져서 하루에 100명 200명 이렇게 사람들이 몰려온다. 이제 어떻게 하지? 그래서 회사에서 엔지니어들이 모여서 TF같은 걸 만들어서 모바일 앱을 통해 주문하고 받아볼 수 있게 그런 앱을 만들어보고자 한다.

Step1. 독자가 누구인지 알아야 합니다.

페르소나 분석

서비스와 관련된 사람들을 3가지로 나누어보자

A : 음료를 주문하는 손님들
B : 바리스타님
C : 현장에서 기기 고장을 수리하는 엔지니어

Step 2. 독자가 할 법한 일들을 열거해 봅니다.

커피를 주문하는 사람 입장에서 시나리오를 한 번 따라가보자.

일단 설치는 어떻게 하지? 로그인은 어떻게 하지? 주문은 어떻게 하지? 등등

중간 질문 - 사내 서비스라면 문제가 뭐가 있을까 -> 설치/업데이트가 굉장히 어렵다. (안드로이드는 좀 나은데 iOS는 굉장히 어렵다)

Testflight 계정같은거 만들기도 어렵고 뭐 어떻게 하지? 난이도가 높다. 이거 문서화 제대로 안 해두면 아무도 못 쓸건데...

이런 식으로 발생할 수 있는 시나리오들을 쭉 열거해보는게 중요하다

Step 3. 독자가 경험할 만한 어려움을 열거해 봅니다.

사용자들은 정말 다양한 경험들을 하게 된다.

일단 생각해보자. 사용자가 앱을 깔려고 하는데, 사내 망에서만 접근 가능해서 VPN이 있어야한다거나... 이런 자잘한 부분부터 아이폰에서는 보안 강화 기능같은걸 켜놓고 쓰면 앱이 깔리지 않는다거나... 이런것들을 열거해보자

-> 이런 것들을 Trouble Shooting Guide로 만들어서 들어가야 한다

그리고 앱 개발할 때는 모든 기능을 다 만들진 않는다. 조금씩 하나하나 업데이트해나가는데, 사용자들 입장에서는 없어서 당황할 수 있다. 그래서 사용자 가이드에 업데이트 예정이다 이런 것도 넣어두면 좋다.

Review

3가지를 기억하라!

누구를 위한 가이드인가?
이 가이드로 알 수 있는 내용은 무엇인가?
이 가이드를 따라할 때 어떤 어려움이 있는가?

마무리... 이런 프레임워크는 다양한 곳에 적용할 수 있다!

예를 들어 기술 블로그를 작성한다고 쳐보자. 쿠버네티스 앱 배포하는걸 쓴다고 했을 때, 이걸 누구한테 얘기할건지 정해야 한다. 쿠베를 아예 모르는 사람, 좀 써본 사람 등등

그다음에 구조같은 것들도 그냥 러프하게 쭉 훑을건지, 세세하게 다 살펴볼건지 그런 것들을 다 생각하면서 써야 함

근데 이걸 의식의 흐름대로 쭉 쓰려고 하면 힘들고 잘 안된다 그래서 계획을 해서 써야 한다. 3가지 포인트를 중심으로

글을 잘 쓰기 위한 노력 5가지

1st. 좋은 표현 많이 익히기

좋은 표현을 많이 익혀라? 그러면 평소에 책 많이 읽고 공부 많이 하란 소리냐? X

그냥 자기 분야랑 더 친하게 지내라는 소리다. 그래야 좋은 표현을 많이 익힐 수 있다.

중간 퀴즈 - 댄스가수 유랑단, 나는가수다, 불후의명곡 - 얘네들 공통점은? 자기 곡이 아닌 노래를 부른다

-> 자기가 쓰려고 하는 글을 잘 쓰는 것도 중요한데, 다른 사람이 쓴 글을 보면서, '이걸 내 스타일대로 쓰면 어떻게 바뀔까?'같은 걸 생각해보면서, 비판적으로 다양한 관점에서 바라보면 좋다 (근데 비난은 아님.) 그렇게 해보면 좋을 것 같음!

좋은 표현을 익힌다는 소리는 KPI로 측정하는 그런 건 아니다

지식들을 스펀지처럼 쫙 흡수해서, 필요할때마다 조금씩 눌러서 쓸 수 있게 하듯, 다양한 콘텐츠를 장르같은걸 가리지 않고 다 습득해봐라

2nd. 비문학적 글쓰기

메모와 문서화는 다르다 - 평소에 쓰는 글이 메모인지, 다른 사람들을 위해서 보여줄 글인지 구분해서 생각해야 한다

비문학적 글쓰기는 기본적으로 다른 사람들이 읽기를 바라면서 쓰는 글임.

비문학적 글쓰기에서 중요한 5가지

날짜와 시점은 정확히, 추측하지 말고 숫자와 데이터를 근거로 서술하기
사물의 상태 변화를 쓸 때만 수동태로, 평소에는 능동태로 명확하게 서술하기 - 정확한 어법을 써서 전달하기

강아지가 공을 쫓는다 vs 공이 강아지에게 쫓기고 있다…
어떻게 써야할까? -> 강아지가 공을 쫓는다 (이런 식으로 상황에 맞게 써야 한다)

의도가 변하지 않으며 말이 된다면 핵심 문장 성분만 남기기

의미전달에 방해되는 불필요한 말은 빼기 = 짧게 쓰는게 유리하다
내 생애 최고의 책을 꼽으라고 하면, 나는 무조건 이 책을 꼽을 것이다. -> 내 생애 최고의 책은 이 책이다.

한자어, 외래어, 영어, 전문 용어는 꼭 필요할 때만 쓰고, 번역체는 멀리 하기

독자가 같은 레벨의 전문가들이라면 전문 용어를 써도 된다 (깔끔하게 이해되니까)
독자가 전문가가 아니라면 전문 용어를 쓰지 말자 (그 사람의 레벨에 맞게 써야 한다)
그리고 생각보다 번역체가 되게 많음. (ex. OO를 하길 요망. 금일/명일/작일 이런 것들) -> 번역체를 쓰지 말자

문단 하나에 세 문장 이하로, 한 가지라도 확실히 전하기

3rd. 일관성 있는 글쓰기

코드와 마찬가지로 글도 일관되어야 해요

솔루션 vs 설루션 - 국립국어원 기준 표준은 '설루션'
Vogue체 - 그냥 아름답다/예쁘다 라는 표현을 뭐 엘레강스하다/비비드하다 이런식으로 비틀어서 있어보이게 잔뜩 치장해서 씀

Writing Style Guide

한국어를 쓰면서 마주치는 상황들.

국립국어원이 표준을 정해놨다. 그런데 사람들이 많이 쓰는게 아닌 경우, 사실상의 표준이 있는 경우. -> 그러면 국립국어원이 무조건 옳다고 보지 않음. 업계에서 많이 사용되는 용어가 있다면 그걸 우선시하는게 맞음

그래서 업계에서 사용하는 용어의 스타일 가이드가 있을거고, 회사에서 사용하는 용어의 스타일 가이드가 있을거고, 팀에서 사용하는 용어의 스타일 가이드가 있을거다.

그래서 독자에 따라서 용어의 스타일 가이드에 맞춰서 통일해야 할 필요성이 있다.

잘 만들어진 대표적인 라이팅 스타일 가이드 추천

Apple Style Guide: https://support.apple.com/ko㎽kr/guide/applestyleguide/welcome/web (opens in a new tab)
Microsoft Writing Style Guide: https://learn.microsoft.com/en㎽us/style㎽guide/welcome/ (opens in a new tab)

짚고 넘어가야 할 한 가지 : 우리 팀에도 이런 스타일 가이드를 만들고 싶은데, 어떻게 하면 좋을까?

용어집을 만들어보는게 좋은 방법이다.

구성원들 간에도 같은 뜻의 단어도 다양한 용어로 사용되는 경우가 많은데, (ex. 구성/설정 등) 그런 것들이 통일되지 않아서 발생하는 문제

도메인에 따라서 달라지는 용어들의 경우 development는 IT 업계에서는 소프트웨어 개발에 대한 이야기인데, 다른 업계에서는 부동산 상품과 같은 의미나, 현재 취재 중이라는 의미로 쓰이기도 한다. 이렇듯 하나의 단어가 다양한 의미로 쓰이는 경우가 많다. 이걸 용어집을 만들어서 하나로 통일하는게 스타일가이드의 시작이라고 볼 수 있다.

4th. 글을 테스트하는 방법

중이 제 머리 못 깎는다. 요리사가 자기 음식 못 먹는다.

자기가 쓴 글을 자기 스스로 탈고하는 것은 쉽지 않다.

하지만, 글을 보는 시점이라던지 수단, 환경같은걸 달리 하면 내가 미처 못 봤던 오류를 찾을 확률이 높아진다.

글을 쓸 때는 집중하고, 글을 읽을 때는 편하게 마음 가는 대로 읽어보세요.
글을 리뷰해줄 분을 찾을 수 있다면 기꺼이 받아 보시고, 답례를 잊지 마세요.
보안에 민감한 콘텐츠가 아니라면 장소를 바꾸어서 다른 환경 속에 앉아 글을 읽어보세요.
스마트폰에서 글을 읽거나, 종이에 인쇄해서 글을 읽어보세요.
텍스트 확대 배율을 조금 높여서 글을 읽어보세요.

그러면 이렇게 해서 문제점을 발견했다! 이제 어떻게 고치지?

타당성

형식적인 부분에서의 완성도과 함께 챙기셔야 할 것이 있어요.
사실과 데이터, 객관성을 근거로 글을 썼는지가 중요합니다.
우리가 쓰는 글은 문학이 아닌 "비문학"이라는 것을 잊으면 안 됩니다.

맞춤법

한국어는 부산대 맞춤법검사기 정도가 제일 낫다

5th. 글쓰기를 넘어서는 정보 전달

글을 잘 쓰기만 하면 정보가 잘 전달될까?

요즘 생각을 해보면, 앱을 개발하고 나서 배포해보면, 생각지도 못한 곳에서 막 터지고 한다

그런데 정보를 전달하는 글을 배포한다. 전혀 문제가 없을 것만 같았는데 문제가 발생될 수 있다.

이걸 텍스트로만 해결하려고 하지 말고, 다양한 수단을 써보자

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

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

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

SEO의 시대는 가고, LLM AI의 시대가 왔다

옛날에는 검색엔진에 잘 뜨도록 하는게 되게 중요했음. 키워드를 어떻게 세팅해야할지, 검색엔진에 잘 맞게 하려면 어떻게 해야하는가, Page에 Abstract가 어떻게 보이는지 등등

그런데 이제는 LLM AI의 시대가 오면서 글쓰기가 중요하지 않아질까? -> 절대 아니라고 생각함

현재의 LLM AI는 스스로 잘못된 내용을 바로 잡을 수가 없다. 그래서 사람이 어떤 정보를 넣었는지가 매우 중요하다.

AI가 나를 대신해서 글을 써주는 것? 기존에 학습된 걸 바탕으로 쓰는 것임.

AI가 더 풍부한 대답을 할 수 있도록 전달을 하고싶다. 그렇게 한다면 어차피 텍스트로 데이터를 전달해야 한다.

요즘은 이걸 검색 증강 생성 (RAG, Retrieval Augmented Generation)이라고 한다.

그 외에 소소한 팁

원격 근무 제도를 잘 활용해보자 -> 글을 쓰는 환경을 다양하게 바꿔보자.
글의 얼개를 메모 툴이나 노션 등으로 빠르게 잡아보자. (글의 꼭지를 잡아서 그걸 토대로 글을 확장해나가보자)
본인이 쓴 한국어 문장을 한영 번역기로 돌려봐라. 어차피 잘 안될꺼긴 한데, 단순명료하고 비교적 잘 번역되는 문장일 수록 좋은 문장일 가능성이 높다.

마무리

기억하세요!

누구를 위한 가이드인가?
이 가이드로 알 수 있는 내용은 무엇인가?
이 가이드를 따라할 때 어떤 어려움이 있는가?

5가지 소프트 스킬

일관성 있는 글 쓰기 : 스타일 가이드
좋은 표현 많이 익히기 : 다양한 콘텐츠를 계속 습득하라
비문학적 글쓰기 : 비문학적 글쓰기에 중요한 5가지를 기억하라
글을 테스트 : 글을 보는 시점이나 수단, 환경같은걸 다르게 해서 써봐라
글쓰기를 넘어서는 정보전달 : 다양한 매체를 활용해서 정보를 전달하라

업무를 객관적으로 바라보는 좋은 방법? -> 업무의 내용/목적/목표/구성원들이 앙ㄹ아야 할 세부사항들을 쭉 정리해보자

그리고 문서화에만 너무 매몰되어 너무 많은 문서만 찍어내는 경우도 가끔 있는데, 문서를 만들때는 꼭 계획에 기초해서 체계적으로 만들어나가야한다 (문서를 제품처럼 생각해봐라)

제품을 문서화하는 것은 거울에 제품을 비추어 보는 것과 같다

제품이 좋지 않으면 그걸 설명하는 문서도 좋을 수가 없다

Q&A

API 문서화 관련된 부분 : LY 테크니컬 라이터 전정은님 - 좋은 툴들 많이 소개해주니까 살펴보면 좋을 듯

Hello World 24 소주콘 Shot6