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

코드를 짜듯 문서 구조를 설계하고, 챗GPT와 소통하는

개발자의 문서 작성법!

최근 IT 현장에서는 단순 코딩 능력을 넘어 PM, 디자이너 등 다양한 직군과 명확히 소통하는 커뮤니케이션 역량이 개발자의 핵심 조건으로 떠오르고 있다. 이 책은 코드를 짜기 전 전체 구조를 설계하듯 정보를 세분화하고 아웃라인을 잡는 '구조적 설계와 절차' 중심의 접근법을 제시한다. 독자와 주제를 좁히는 기초 단계부터 '왜, 무엇을, 어떻게'라는 3대 요소를 활용한 뼈대 작성 패턴을 전수해 요구사항 정의서, 기능 명세서, 보고서 등 실무 문서를 논리적으로 완성하도록 돕는다. 나아가 챗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 ‘개요에서 상세로’ 흐름

찾아보기

[본 문]

문서 작성에 부담을 느끼는 개발자가 참 많습니다. 이 책을 손에 든 여러 분도 비슷하시겠지요. 혹은 ‘그냥 대충 쓰고는 있는데, 내가 잘 쓰고 있는 게 맞나?’ 하는 의문이 들지도 모릅니다. 당연한 일입니다. 현실적으로 개발자가 문서 작성법을 제대로 배울 기회 는 그리 많지 않으니까요. 최근 관련 수업을 개설하는 학교가 늘고 있고 저 또한 강의를 하고 있지만, 여전히 대다수 개발자에게는 기회조차 닿지 않는 게 사실입니다. 배운 적이 없으니 글쓰기에 서툴고 자신 없는 것은 너무나 당연합니다. 반면 문서를 읽고 쓰는 능력은 개발자의 필수 역량입니다. 기술 명세서부 터 매뉴얼, 보고서, 블로그 포스팅까지, 개발 현장에서 문서를 단 한 번도 써보지 않은 개발자는 없을 것입니다. 문서는 정보를 효율적으로 전달하는 강력한 수단입니다. 이에 더해 글을 쓰는 행위 자체로도 큰 이점이 있습니다. 복잡하게 얽혀 있던 머릿속 정보 가 세분화되고 정리되면서, 논리적인 체계와 구조를 갖추게 되기 때문입 니다. 이 책은 단순히 문장 다듬는 법만 다루지 않습니다. 전달하려는 정보를 어 떻게 정리하고 구성할지에 중점을 두고, ‘독자에게 명확하게 전달되는 문 서’를 만드는 법을 설명합니다. 아무리 복잡한 정보라도 적절한 구조를 갖 추면 읽는 사람이 훨씬 이해하기 쉬워집니다. 책은 1장만 읽어도 전체 개요를 빠르게 파악할 수 있도록 구성했습니다. 따라서 1장은 꼭 먼저 읽어 보기를 권합니다. 2장부터는 순서대로 읽어도 004 좋고, 평소 고민이었던 작성 단계만 골라 읽어도 괜찮습니다. 필요한 정보 만 골라 읽을 수 있다는 점이야말로, 이 책이 강조하는 ‘좋은 문서’의 장점 이니까요. 이 책은 제가 대학에서 강의하는 내용을 바탕으로 집필했습니다. 여러분 도 편안하게 학생이 된 기분으로 읽어 주었으면 좋겠습니다. 책장을 모두 덮을 때쯤이면, 문서 작성을 향한 두려움이나 막막함은 어느새 사라져 있 을 것입니다. 그럼, 즐거운 마음으로 수업을 시작해 볼까요?

_ 「들어가며」 중에서