안녕하세요. 테크니컬 라이터, 정나래입니다.

테크니컬 라이터는 복잡한 기술 정보를 사용자가 쉽게 이해하고 활용할 수 있도록 문서화하는 사람입니다. 저는 주로 개발자를 대상으로 한 API 문서를 작성하고 있습니다. 이 외에도 다양한 직군의 글을 다듬는 일을 하고 있어요. 오늘은 개발자 분들이 문서화할 때 자주 놓치는 부분을 이야기해 보려 합니다. 

코드와 글은 완성도를 확인하는 방식부터 다릅니다. 코드는 컴파일이 안 되거나 테스트가 실패하면 바로 티가 나지만, 글은 그런 피드백 루프가 없습니다. 우리 머릿속에서는 논리가 완벽하게 이어져도, 독자는 이해하지 못할 수 있습니다. "분명히 다 설명했는데 왜 이해를 못 하지?"라는 상황이 반복되는 이유입니다.

이 부분을 AI에게 맡긴다고 해서 저절로 해결되지는 않습니다. 왜 여전히 아쉬운 결과물이 나오는지도 함께 짚어보겠습니다.

• 개발자가 흔히 하는 글쓰기 실수

1. 내가 아는 것을 다 설명한다

많은 개발자 분들이 하는 실수는, 알고 있는 정보를 문서에 모두 담으려 하는 것입니다. 그러다 보면 길이는 길어지고, 애매한 설명과 독자 수준에서 이해하기 어려운 문장은 오히려 독자의 이해를 방해하게 됩니다.

문서를 쓰기 어려워하는 사람들 대부분이 '작성자 중심'으로 씁니다. 문서의 목적은 자신이 아는 지식을 모두 전달하는 것이 아니라, 독자에게 필요한 정보를 전달하는 것인데도, 배경 설명이나 논의 과정, 변경 이력까지 다 담으려 하는 거죠. 독자는 그 맥락을 전혀 모른 채 문서를 읽는다는 사실을 자주 잊습니다.

✅개선 방향: 독자가 필요한 정보만 담으세요

글을 쓰기 전에 먼저 물어보세요. 이 글을 읽는 사람이 누구인지, 그들이 궁금해하는 것이 무엇인지를요. 읽는 사람의 배경 지식과 목적을 고려하지 않은 글은, 독자가 원하는 정보를 얻어가지 못하는 글이 됩니다.

새로운 시스템을 소개하는 문서를 예로 들어볼게요. 독자가 개발자가 아니라면, 시스템의 플로우나 기술 스택까지 담을 필요가 없습니다. 그 독자에게 필요한 건 "기존과 무엇이 다른지, 어떻게 사용하는지"가 전부예요. 반대로 같은 내용도 개발자 독자에게는 완전히 다르게 써야 합니다.

일반 사용자에게는 버튼 클릭이라는 행동 중심으로, 개발자에게는 인증 방식과 엔드포인트 같은 기술 명세 중심으로 씁니다. 개발자에게 익숙한 런타임, 빌드, 스키마, 컨테이너 같은 용어도 독자에 따라 낯설 수 있다는 점, 반대로 개발자 독자에게는 배경 설명을 최소화하고 핵심 정보와 기술 명세만 간결하게 전달해야 한다는 점, 둘 다 기억해 주세요.

2. 글이 장황하고 결론을 찾기 어렵다

머릿속에 많은 정보를 글로 쏟아내다 보면 문장이 길어지고, 결론이 뒤로 밀립니다. 수식에 수식이 붙어 한 문장을 여러 번 읽어야 하는 상황이 생기죠. 독자는 글을 처음부터 끝까지 꼼꼼히 읽지 않습니다. 핵심이 어디 있는지 모르면, 읽다가 그냥 닫아버립니다.

✅개선 방향: 초안은 쏟아내고, 퇴고에서 추려내세요. 핵심을 가장 먼저!

괜찮습니다. 초안부터 완벽한 글을 쓰는 사람은 드뭅니다. 처음 쓸 때는 정보와 생각을 자유롭게 쏟아내고, 그 이후에 글을 읽고 또 읽으면서 독자에게 필요한 정보만 추려내면 됩니다.

이때 참고할 만한 원칙이 BLUF(Bottom Line Up Front, 결론부터 말하기)입니다. 원래 미군이 긴급 상황에서 핵심 정보를 먼저 전달하기 위해 쓰던 커뮤니케이션 원칙인데, 업무 글쓰기에도 그대로 적용됩니다. 배경 설명부터 시작해 결론을 마지막에 두는 습관을 뒤집는 거예요.

수정 전의 내용은 끝까지 읽어야만 "뭘 해야 하는지" 알 수 있습니다. 수정 후는 첫 문장에서 바로 무엇을 해야 하는지 파악됩니다. 그리고 남은 정보들 중에서 핵심 메시지를 먼저 배치하세요. 독자가 가장 궁금해하는 정보를 먼저 주고, 배경 설명은 필요한 사람만 읽도록 뒤에 배치하는 것이 좋습니다

문장을 늘어지게 하는 요소들도 함께 손봐야 합니다.

• 수식어 제거: '매우', '굉장히', '특별히' 같은 표현은 삭제해도 의미가 달라지지 않는 경우가 많습니다. 강조가 필요하면 수식어 대신 정확한 단어나 수치를 씁니다. (예: "굉장히 빠른 속도로 처리됩니다" → "1초 내로 처리됩니다")
• 중복 표현 제거: "가장 최신 버전", "다시 한번 재확인" 처럼 의미가 겹치는 표현은 하나만 남깁니다.

마지막으로 한 문장에 여러 내용을 담는 것보다, 한 문장에 하나의 핵심만 전달하는 것이 훨씬 잘 읽힙니다.

3. 설명은 있는데 행동 지침이 없다

기술 문서나 사용 안내 문서를 보면, 기능이 왜 만들어졌는지, 어떤 구조로 동작하는지, 각 기능은 무엇인지에 대한 자세한 설명은 있는데, 정작 이 기능을 "어떻게 하면 되는지"가 빠진 경우가 많습니다. 독자 입장에서는 설명을 다 읽고도 다음에 무엇을 해야 할지 모르는 상황이 생겨요. 그 기능을 만든 사람이 아니라, 사용할 사람을 염두한 글이 되어야 합니다.

✅개선 방향: 독자가 취해야 할 행동을 명확히 안내하세요

사용자가 알고 싶은 건 이 기능이 왜, 어떻게 개발되었는지보다 어떻게 사용하는지입니다. 다음은 자주 나오는 실수와 개선 예시입니다.

수정 전은 이 API가 왜, 어떻게 만들어졌는지는 설명하지만, 정작 독자가 필요한 어떻게 사용하는지는 담고 있지 않습니다. 수정 후는 그 개발 배경 대신, 독자가 바로 실행할 수 있는 절차로 채웠습니다.

한 가지 더, 문서를 따라가다 마주칠 수 있는 예외 상황을 미리 안내해 두는 것도 좋습니다. 정상 흐름뿐 아니라 오류 메시지, 실패 조건, 대응 방법까지 함께 안내해야 독자가 길을 잃지 않습니다.

정보를 전달하는 데서 끝내지 말고, 독자가 읽고 나서 무엇을 해야 하는지까지 담아야 문서가 완성됩니다.

4. 구조 없이 정보를 쏟아낸다

정보량이 많을수록 구조 설계가 중요합니다. 그런데 내용을 작성하는 데 집중하다 보면 전체 흐름을 놓치기 쉬워요. 목차가 없거나 섹션 구분이 불분명하면, 독자는 원하는 정보를 찾다가 지칩니다.

✅개선 방향: 목차가 글의 지도가 되도록 설계하세요

사람들은 문서를 읽을 때 일정한 시선 패턴을 보입니다. Nielsen Norman Group의 아이트래킹 연구에 따르면 크게 두 가지 패턴이 있는데요, 상단과 왼쪽에 시선이 먼저 집중되는 F 패턴, 그리고 제목과 소제목만 수평으로 훑는 레이어케이크 패턴입니다. 즉 독자는 소제목만 보고도 필요한 구간을 찾아가려 한다는 뜻입니다.

목차만 봐도 글의 흐름이 보여야 하고, 각 섹션의 핵심이 제목으로 드러나야 해요. 그래야 독자가 전체를 읽지 않아도 필요한 정보를 빠르게 찾을 수 있습니다.

구조를 잡을 때는 문서 유형을 먼저 구분하는 것도 도움이 됩니다. 개발 문서는 크게 세 가지 유형으로 나뉩니다.

• 절차형: '어떻게 한다'에 집중. 설치 가이드, 튜토리얼처럼 순서대로 따라가는 문서. 번호 중심 구조 + 명령형 문장이 기본입니다.
• 개념형: '무엇이고 왜 그런지' 설명. 아키텍처 설명서, 기능 개요 문서처럼 이해가 먼저 필요한 문서. 비유나 다이어그램을 적극 활용합니다.
• 참조형: 필요한 값·용어·에러 코드를 빠르게 찾기 위한 문서. API 명세서, FAQ가 대표적이며 표와 목록 중심의 검색 친화적 구조가 핵심입니다.

같은 정보라도 어떤 유형으로 쓸지 먼저 정하면, "이걸 다 설명해야 하나, 순서로 나열해야 하나, 표로 정리해야 하나" 하는 고민이 훨씬 줄어듭니다.

• AI로 쓴 글이 티 나는 이유
 

많은 분들이 AI로 글을 작성하고 계실텐데요. 형식과 구조, 깔끔한 말투, 대충 훑어보면 잘 쓴 것 같지만, 톺아보면 AI가 쓴 티가 납니다.

왜 그럴까요? AI에게 글의 목적과 독자 정보를 주지 않으면, AI는 정형화된 글을 쏟아냅니다. 그 한계는 대체로 이런 모습으로 드러납니다.

• 내용이 뻔하고 얕다: '좋은', '중요한', '빠르게', '약간'처럼 두루뭉술한 표현이 반복되기도 해요. 독자가 판단에 활용할 만한 사례, 수치, 비교 기준은 빠져 있는 경우가 많습니다. AI는 기존 데이터를 평균화해 가장 그럴듯한 문장을 만들기 때문에, 틀린 말은 아니어도 깊이 있는 해석까지 나아가지는 못합니다.
• 문장이 장황하고 반복적이다: 같은 의미를 여러 표현으로 되풀이하거나, 없어도 되는 연결어와 수식어를 덧붙이는 경향이 있습니다. 한 문장만 보면 자연스러워 보여도, 여러 문장을 이어 읽으면 같은 말이 반복된다는 인상을 줍니다.
• 구조는 그럴듯하지만 설득력이 약하다: 도입-본론-결론 형식은 안정적으로 갖추지만, 막상 읽어보면 중심 주장에 힘이 없거나 근거가 충분하지 않은 경우가 많습니다.
• 단어 선택이 약하다: 의미 범위가 넓은 단어가 반복되면 문장은 무난해 보여도 구체적인 인상을 남기지 못합니다.

구체적인 수치나 맥락을 주지 않았으니, AI도 그 이상의 표현을 할 수 없는 겁니다.

결국 AI 글이 뻔한 게 아니라, 내가 누구를 위해 어떤 정보를 어떻게 전달할지 아직 명확히 정리되지 않았기 때문입니다. AI가 놓치는 것도 앞서 이야기한 원칙과 같습니다. 독자를 고려하고, 핵심을 먼저 제시하고, 기대하는 행동을 달성하도록 정보를 줘야 AI도 그에 맞는 답을 줄 수 있어요.

AI와 함께 글을 쓸 때는 명확한 요청이 명확한 결과물을 만든다는 사실을 꼭 기억해 주세요.

테크니컬 라이터 정나래 드림

『AI도 모르는 글쓰기』

생성형 AI 덕분에 초안 쓰기는 쉬워졌지만, 그 초안을 그대로 활용하기는 어렵습니다. 
어딘가 어색하고, 논리가 매끄럽지 않고, 정작 전해야 할 메시지는 묻혀있습니다. 
이 책은 바로 그 '한 번 더 고치는 순간'에서 출발합니다. 

AI가 만든 그럴싸한 초안 속에서 논리적 비약을 찾아내고,
완성도 높은 문서로 다듬는 노하우를 담았습니다.

카카오 테크니컬 라이터의 눈으로 AI가 놓친 마지막 10%를 채워드립니다.