개발자가 문서 작성도 잘해야 하나요?(글쓰기의 기본은 물론, AI와 함께 쓰는 법까지!)

주제 선정부터 문서 구성, 패러그래프, 문장 다듬기, 챗GPT 활용까지!
한 번 익히면 평생 가는 가장 실전적인 개발자의 글쓰기!

글쓰기도 설계가 먼저다
무작정 첫 문장부터 쓰려니 머릿속이 하얘진다. 개발자에게 익숙한 방식은 따로 있다. 바로 설계이다. 이 책은 문서를 '누구에게, 무엇을 전달할 것인가' 정하는 일부터 시작해, 주제를 잘게 쪼개고 아웃라인을 세운 뒤 문장을 채우는 순서를 따른다. 코드를 짜기 전 아키텍처부터 그리는 개발자의 감각을, 그대로 글쓰기에 옮겨 놓은 셈이다.
한 번 세운 구조는 어떤 문서에도 통한다
요구사항 정의서, 기능 명세서, 사용자 매뉴얼, 보고서, 그리고 챗GPT에게 던지는 질문까지, 형식은 달라도 좋은 문서를 만드는 원리는 같다. 이 책은 그 원리를 다섯 단계로 정리하고, 실제 업무에서 바로 옮겨 쓸 수 있는 구성 예시와 생성형 AI 활용법까지 함께 담았다. 한 번 몸에 익히면, 어떤 문서도 더 이상 막막하지 않을 것이다.

PART 1 기초편

CHAPTER 1 | 좋은 문서를 효율적으로 작성하기
1.1 개발자가 문서를 작성하는 목적
__1.1.1 설명형: 개념이나 절차를 설명한다
__1.1.2 보고형: 지식과 활동을 보고한다
__1.1.3 설득형: 의견이나 제안을 전달해 상대방의 행동을 유도한다
1.2 좋은 문서의 세 가지 요소
__1.2.1 유효성: 필요한 정보를 정확하게 얻을 수 있다
__1.2.2 효율성: 적은 노력으로 빠르게 이해할 수 있다
__1.2.3 만족도: 거부감 없이 긍정적으로 받아들일 수 있다
1.3 글쓰기와 프로그래밍의 공통점
__1.3.1 초기 설계가 중요하다
__1.3.2 내용을 나타내는 제목을 붙인다
__1.3.3 하나의 함수에 하나의 역할만 부여한다
__1.3.4 코드를 공통화한다
1.4 글쓰기에 대한 부담감
__1.4.1 무엇을 써야 할지 모르겠다
__1.4.2 어디서부터 써야 할지 모르겠다
1.5 글을 쓰기 전에 주제를 나눈다
1.6 문서 작성의 흐름
__1.6.1 독자와 주제 선정하기
__1.6.2 주제 나누기
__1.6.3 문서 구성하기
__1.6.4 문장 구성하기
__1.6.5 문장 쓰기

CHAPTER 2 | 문서 읽는 방법을 이해하기
2.1 계층 구조를 이해하면 문서를 효율적으로 읽을 수 있다
2.2 문서는 계층 구조를 가진다
__2.2.1 문서 전체의 주제를 나타내는 제목
__2.2.2 하위 주제를 나타내는 소제목
__2.2.3 제목과 소제목을 보완하는 도입부
__2.2.4 하나의 주제를 나타내는 패러그래프
__2.2.5 패러그래프에서 '말하고자 하는 바'를 나타내는 핵심 문장
2.3 사전형과 읽기형에 따라 읽는 방식
__2.3.1 사전형 문서는 읽는 목적이 명확하다
__2.3.2 읽기형 문서는 읽는 목적이 모호하다
2.4 사전형 문서는 추측하면서 읽는다
__2.4.1 제목을 통해 전체 내용을 추측하기
__2.4.2 소제목을 통해 원하는 내용을 탐색하기
__2.4.3 생각할 점: 구체적인 제목과 소제목이 검색의 효율성을 높인다
__2.4.4 생각할 점: 정보를 구조화하면 탐색하기 쉬워진다
2.5 읽기형 문서는 요점을 파악하면서 읽는다
__2.5.1 도입부에서 전체 개요를 파악하기
__2.5.2 소제목을 통해 요점 파악하기
__2.5.3 핵심 문장에서 패러그래프의 요점을 파악하기
__2.5.4 생각할 점: 요점을 먼저 전달해야 문서의 가독성을 높인다
__2.5.5 생각할 점: 정보를 구조화하면 이해하기 쉬운 문서를 만들 수 있다

CHAPTER 3 | 독자와 주제 선정하기
3.1 독자 맞춤형 문서 만들기
3.2 문서의 목적을 명확히 하기
__3.2.1 독자: 누구에게 전할 것인가
__3.2.2 주제: 무엇을 전달할 것인가
3.3 독자 이해하기
__3.3.1 독자의 지식 수준을 이해하기
__3.3.2 독자의 목적을 이해하기
__3.3.3 독자의 직무·역할을 이해하기
3.4 독자를 이해하기 위한 정보원
__3.4.1 관계자에게 물어보기
__3.4.2 문의 내용을 참고하기
__3.4.3 사용자 테스트에 참여하기
3.5 독자와 주제를 좁히기
__3.5.1 독자 좁히기
__3.5.2 주제 좁히기

CHAPTER 4 | 주제 세분화하기
4.1 주제 세분화는 적절한 문서 구성으로 이어진다
__4.1.1 논리적인 구성으로 만들 수 있다
__4.1.2 복잡한 정보를 정리할 수 있다
__4.1.3 정보를 찾기 쉬운 구성이 된다
4.2 주제를 구성하는 세 가지 요소
4.3 주제를 '왜, 무엇을, 어떻게'로 세분화하기
__4.3.1 설명형 문서
__4.3.2 설득형 문서
__4.3.3 보고형 문서
4.4 큰 주제를 세분화하기
__4.4.1 구성 요소로 세분화하기(전체에서 부분으로)
__4.4.2 구체적인 예로 세분화하기(개요에서 상세로)
4.5 읽는 사람의 목적에 맞춰 세분화하기

CHAPTER 5 | 문서의 뼈대를 세우기
5.1 문서의 뼈대 = 아웃라인
5.2 아웃라인의 역할
__5.2.1 작성자를 위한 역할 1: 논리 구성하기
__5.2.2 작성자를 위한 역할 2: 어디에 무엇을 쓸지 결정한다
__5.2.3 읽는 사람을 위한 역할 1: 필요한 정보를 찾는 단서
__5.2.4 읽는 사람을 위한 역할 2: 요점을 파악하는 단서
5.3 세분화한 주제에서 아웃라인 만들기
__5.3.1 1 단계: 요소를 다시 배열한다
__5.3.2 2 단계: 소제목으로 올릴 요소를 고르기
__5.3.3 3 단계: 소제목 문구를 정한다
__5.3.4 4 단계: 소제목만 쭉 읽어 보며 최종 점검하기
5.4 아웃라인 예시
__5.4.1 설명형 문서의 아웃라인
__5.4.2 설득형 문서의 아웃라인
__5.4.3 보고형 문서의 아웃라인

CHAPTER 6 | 문장 쓰기
6.1 하나의 화제를 정리하는 패러그래프
__6.1.1 패러그래프로 하고 싶은 말을 딱 잘라 말한다
__6.1.2 하고 싶은 말의 이유나 설명을 곁들인다
6.2 화제의 묶음을 의식하면 쓰기 쉬워진다
6.3 패러그래프를 전개하는 세 가지 패턴
__6.3.1 하고 싶은 말의 이유를 서술한다
__6.3.2 하고 싶은 말의 설명을 서술한다
__6.3.3 하고 싶은 말의 구체적인 예를 든다
6.4 패러그래프 구성하기
__6.4.1 1 단계: 패러그래프를 구성할 요소를 고른다
__6.4.2 2 단계: 각 패러그래프에서 하고 싶은 말을 쓴다
__6.4.3 3 단계: 이야기의 흐름을 확인한다
__6.4.4 4 단계: 하고 싶은 말의 이유나 설명을 쓴다
6.5 나열된 정보는 표현을 통일한다

CHAPTER 7 | 알기 쉬운 문장으로 쓰기
7.1 알기 쉬운 문장이란 무엇인가
7.2 효율적으로 이해하게 쓰기
__7.2.1 중요한 것부터 쓰기
__7.2.2 독자 관점에서 쓰기
__7.2.3 능동태와 수동태를 구분해서 쓰기
__7.2.4 간결하게 쓰기
__7.2.5 쉼표나 목록으로 병렬 관계를 분명하게 하기
7.3 정확하게 이해하게 쓰기
__7.3.1 구체적으로 쓰기
__7.3.2 쉼표나 어순으로 수식 관계를 명확하게 한다
__7.3.3 의미를 명확하게 하기 위해 긍정형으로 쓰기
7.4 긍정적으로 받아들이게 쓰기
__7.4.1 긍정적으로 전하기 위해 긍정형으로 쓰기
__7.4.2 신뢰받는 표현으로 쓰기
__7.4.3 지나치게 공손한 표현은 쓰지 않기

CHAPTER 8 | 챗GPT로 문서를 효율적으로 쓰기
8.1 문장을 자동으로 순식간에 만들어 내는 챗GPT
8.2 모르는 것은 쓸 수 없는 챗GPT
8.3 챗GPT에 '전적으로 맡기지' 말고 '도움을 받는다'
8.4 챗GPT로 문서의 구성을 짜기
__8.4.1 명세서 구성 작성하기
__8.4.2 구성안 평가하기
__8.4.3 구성이 적절하게 짜여 있는가
__8.4.4 항목의 순서가 적절한가
8.5 챗GPT로 문서 초안 작성하기
__8.5.1 설명형 문서: 매뉴얼의 초안을 작성하기
__8.5.2 초안 평가하기
__8.5.3 기획서의 초안을 작성하기(설득형 문서)
__8.5.4 보고서의 초안을 작성하기(보고형 문서)
8.6 챗GPT로 문장 교정하기
__8.6.1 오탈자 수정하기
__8.6.2 알기 쉬운 문장으로 고치기

PART 2 실습편

CHAPTER 9 | 구성 예시
9.1 요구사항 정의서
__9.1.1 '왜, 무엇을' 구성하기
__9.1.2 '전체에서 부분으로' 흐름
9.2 기능 명세서
__9.2.1 '왜, 무엇을' 구성하기
__9.2.2 '전체에서 부분으로' 흐름
9.3 사용자 매뉴얼
__9.3.1 '왜, 무엇을, 어떻게' 구성하기
__9.3.2 '전체에서 부분으로' 흐름
9.4 보고서
__9.4.1 '왜, 무엇을, 어떻게' 구성하기
__9.4.2 '개요에서 상세로' 흐름

찾아보기

나카타 나오히로 테크니컬 라이터이자 UX 라이터이다. 주로 소프트웨어의 UI 텍스트와 문서(매뉴얼, 릴리스 노트, 테크니컬 문서 등)를 작성하는 일을 전문으로 하며, 이러한 문서의 현지화에도 참여하고 있다. 사이보즈(Cybozu)에서 테크니컬 라이터와 현지화 부문 매니저를 거쳐, 2024년부터 SmartHR에서 근무하고 있다. 본업과 병행하여 기업과 학생을 대상으로 테크니컬 라이팅 세미나도 진행한다. Developers Summit 2023 어워드를 수상했으며, 도쿄도립 산업기술고등전문학교에서 비상근 강사로도 활동하고 있다. 저서로는 『도움말 사이트 만드는 법』(기술평론사)이 있다.
X · @naoh_nak