개발자의 글쓰기 - 김철수

 

 

 

개발자의 글쓰기 (http://www.yes24.com/Product/Goods/79378905)

변수 네이밍부터 릴리스 노트, 장애 보고서, 기술 블로그까지, 프로그래머의 글쓰기 고민 끝!

김철수 저 | 위키북스 | 2019년 10월 04일

 

---

프롤로그

개발자 글쓰기 특징 : 정확성, 간결성, 가독성

​

1. 개발자가 알아야 할 글쓰기 기본

1. 문장과 단락을 구조화하는 법

문장을 구조화 하는 법

• “입력 데이터는 3차원 벡터다. 색상 RGB 값을 각각 사용하기 때문이다.”
• 간단한 문장구조로 핵심을 말한 뒤 필요에 따라 부가 설명을 하면 된다.

​

서술식, 개조식, 도식의 차이

• 서술식 : ~다 로 끝나는 문장
• 개조식 : 명사(완료, 증가), 용언의 명사형(~했음) 등으로 끝나는 문장
• 도식 : 표나 그림으로 표현

​

개조식 서술 방식과 글머리 기호

글의 진술방식 4가지

• 설명 : 내용을 구체적으로 설명하거나 나열할 때 ◻︎, ◼︎, ○, ●, - 등을 사용
• 묘사 : 내용을 그림으로 나타낼 때 그림안에 어떤 요소나 영역을 표시하기 위해서 ⓐ, ⓑ, ①, ② 원형문자 사용
• 논증 : 내용이 논리관계로 구성될 때 >, <, = 등을 사용
• 서사 : 순서나 단계를 나타낼 때는 1, 2, 3, 가, 나, 다 등 숫자나 문자를 사용

​

단락을 구조화하는 위계

• 비지니스 문서에는 문단과 문단 사이에 위계가 있어야 한다.
• 비지니스 문서에 위계가 없으면 비즈니스 문서가 아니라 소설이 된다.
• 계층은 3차원 입체의 높이를 뜻한다. 문서에서 계층은 굵기, 모양, 밑줄, 줄 간 거리 등으로 표현된다.
• 비즈니스 문서에서 위치와 계층은 항상 붙어 다닌다.
• 위치만 있어서도 안 되고 계층만 있어서도 안 된다.
• 글을 쓸 때는 항상 위계가 잘 드러나게 글을 쓰고 표현해야 한다.

​

2. 쉽게 쓰는 띄어쓰기와 문장 부호

가장 쉬운 띄어쓰기 원칙

• 조사, 순서, 숫자, 하다, 기호만 붙이고 나머지는 띄어 쓴다.
• 개발자가 굳이 맞춤법 규정을 찾을 필요는 없다.
• 네이버 블로그나 브런치 등 전문 글쓰기 플랫폼은 글을 쓸 때 맞춤법 교정 기능을 제공한다.
• 이곳에 글을 올릴 때 먼저 비공개로 올리면서 맞춤법을 교정한 뒤 복사에서 붙여넣는 방법을 추천한다.

​

오해하기 쉬운 문장 부호(큰따옴표, 작은따옴표)

​

3. 영어 단어 선택과외래어 표기법

비슷한 듯 다른 듯, 단어 선택

• 정확한 단어를 쓰는 것도 중요하지만 그보다 더 중요한 것은 얼마나 일관성있고 개연성 있게 쓰느냐다

​

외산 제품 표기와 외래어 표기법

• 이미 굳어진 외래어는 관용을 존중하되, 그 범위와 용례는 따로 정한다.

​

​

2. 개발 시간을 줄여주는 이름 짓기와 주석 쓰기

1. 네이밍 컨벤션, 이유를 알고 쓰자

개발자의 가장 큰 고민은 이름 짓기

이름 짓기는 창조가 아니라 조합

코드의 네이밍 컨벤션은 영어 표기법을 상속받았다

파스칼 표기법으로 클래스 이름 짓기

​

​

3. 사용자와 소통하는 에러 메시지 쓰기

1 에러 메시지를 쓰기 전에 에러부터 없애자

기획, UX 에 대한 이야기

​

​

4. 독자 관점에서 릴리스 문서와 장애 보고서 쓰기

1 체인지 로그를 분류, 요약, 종합하는 법

​

2 고객에게 유용한 정보를 쓰자

개발자 관점과 고객 관점

과거를 리뷰하고 미래를 보여주자

​

3 릴리즈 문서는 문제 해결 보고서처럼 쓰자

문제와 문제점을 구별하자

문제, 문제점, 해결책, 후속 계획 순으로 적자

법적인 문제를 고려해서 쓰자

​

4 비즈니스를 이해하는 장애 보고서 쓰기

​

​

5. 설명, 묘사, 논증, 서사로 개발 가이드 쓰기

1 서비스 개념을 범주, 용도, 특징으로 설명하자

범주를 정확하고 적절하게 선택하자

범주는 서비스를 소개하거나 설명하는 첫 문장인 만큼 정확하고 적절하게 해야한다.

가장 좋은 방법은 여러 경쟁사가 사용하는 보편적인 서비스 범주를 따라 하는 것이다.

범주는 서비스의 정체성을 나타낼 뿐만 아니라 검색어와도 연관이 있다.

많은 문서의 첫 문단, 첫 문장에 범주가 사용되는 이유가 여기에 있다.

​

용도를 범주의 핵심 기능으로 기술하자

용도는 독자가 이 서비스를 이용하는 이유다.

서비스의 핵심 기능을 쓰면 용도를 기술할 수 있다.

​

특징을 장점과 강점에서 뽑아 쓰자

범주와 용도에는 보편적인 내용을 적는다. 하지만 특징은 차별화하는 내용을 적어야한다.

개발자에게 차별화는 서비스의 장점과 강점이다.

장점은 자기 기준에서 잘하는 것이고, 강점은 경쟁 서비스와 비교해서 나은 것이다.

서비스 개념에서 특징을 쓸 때는 장점이자 강점인 것을 쓰는 것이 가장 좋다.

장점이자 강점인 것이 없다면 장점과 강점을 합쳐서 한 문장으로 쓰는 것도 좋은 방법이다.

​

2 정확히 이해하도록 그림과 글로 묘사하자

글에 묘사를 더하면 이해가 빠르다

묘사는 어떤 대상이나 사물, 현상을 언어로 서술하거나 그림을 그려서 표현하는 것이다.

​

글과 그림의 내용을 일치시키자

개발문서에는 글과 코드만 들어가지 않는다. 그림이나 사진이 많다.

글과 그림이 같은 용어를 사용하는지 꼭 확인해야한다.

같은 것을 다르게 표현하는 순간 독자는 헷갈리기 시작하고 그 결과는 에러로 나타난다.

​

객관적 묘사와 주관적 묘사 둘 다 하자

묘사에는 객관적 묘사와 주관적 묘사가 있다.

기획자에게 객관적 묘사를 기대할 수 없으므로 스스로 주관적 묘사를 객관적 묘사로 바꿔야한다.

예를 들면 객관적 묘사로 요구사항을 정리하고 질의서를 만들어야한다.

개발자가 주관적 묘사를 객관적 묘사로 바꾸고, 그것을 다시 주관적 묘사로 바꿀 수 있으면 일하기가 한결 편하다.

기획자나 디자이너는 주관적 묘사에 익숙하고 객관적 묘사에 서투르다.

개발자가 주관적 묘사와 객관적 묘사 둘 다 잘하면 기획자나 디자이너와 협의할 때 주도권을 가질 수 있다.

개발자가 주도권을 가지면 비교적 개발이 쉬워지고 나중에 변경 할 것도 줄어든다.

​

3 논증으로 유용한 정보를 제공하자

의견을 쓰려면 근거를 대자

논증은 옳고 그름을 이유나 근거를 들어서 밝히는 것이다.

논술과 비슷한데, 논술은 논증의 기법으로 기술하는 것이다.

논술의 핵심이 논증인 셈이다.

논증은 객관적이고 논리적인 방식으로 어떤 사실을 증명해서 상대를 설득하는 일이다.

​

거칠게도 공손하게도 쓰지 말자

개발자가 개발 가이드 문서를 쓰면 은근히 대장 노릇을 할 때가 있다.

자기도 모르게 권력과 힘을 드러내거나 자랑한다.

대표적인 것이 ‘~할 수 있지만 ~하기 어렵다’ 같은 문장이다.

​

주장과 이유의 거리를 좁혀서 쓰자

​

문제와 답의 거리를 좁혀서 쓰자

​

4 서사를 활용해 목차를 만들자

개발과 서사

서사는 사실을 있는 그대로 순서대로 적는 것을 말한다.

누가 어떤 행동을 했고, 그 행동으로 어떤 일이 일어났는지 그대로 쓰는 것이다.

개발에서도 서사를 많이 쓴다.

소설과 다른 점은 독자에게 일어난 사건을 알려주는 것이 아니라, 어떤 일을 하라고 지시한다는 것이다.

​

독자의 수준 대신 기술의 범용성을 기준으로 쓰자

서사가 순서대로 글을 쓰는 것이기는 하지만 단순한 사건이나 상황을 시간순으로 무조건 기술하는 것은 아니다.

그것보다는 의미 있는 사건을 시간에 따른 전개 과정으로 써야 한다.

그래야 서사다.

개발문서에서 서사는 결국 개발자와 독자 사이의 줄다리기 같은 것이다.

개발자는 의미 없는 것은 빼고 중요한 것은 넣기를 원한다.

독자도 의미 있는 것만 남고 무엇이 중요한지 구별해 주기를 원한다.

​

순서에서 단계를, 단계에서 목차를 만들자

개발 가이드나 사용법, 도움말 등의 문서에 서사가 많다.

독자가 프로그램을 에러 없이 순서대로 사용하도록 하기 위해서다.

그런데 어떤 복잡한 것을 순서대로 말하려면 글이 너무 길어진다.

게다가 앞뒤 맥락이 연결되는 것도 있지만, 크게 바뀌는 경우도 있다.

​

단계에는 반드시 목표가 있어야 한다. 그래야 단계를 통과할 수 있다.

이런 부류의 문서는 대부분 처음에는 쉽고 뒤로 갈수록 어려워진다.

그래서 첫단계에서 쉬운 목표를 달성하면서 조금씩 어려운 단계의 목표를 달성하게 만들어야한다.

​

단계를 잘 만들었다면 목차로 사용할 수 있다.

​

​

6. 수주를 돕는 SI 제안서 쓰기

1 개발자가 알아야 할 제안서 작성 원칙

개발자와 제안 PM의 차이

제안서에서 개발자는 주로 기술 부문을 쓴다.

개발자가 기술 부문에서 쓰기 어려운 것은 목적, 목표, 전략, 방안, 기대효과 같은 것이다.

​

시스템 구성도의 본질은 그림이 아니다

​

첫째, 제안요청서 분석

제안요청서에는 목표 시스템, 하드웨어 구성도, 소프트웨어 구성도, 요구 기능, 구매 소프트웨어 목록 같은 것이 이미 들어 있다.

그런데 그렇게 하는 이유와 배경, 상황과 답 또한 모두 다 제안요청서에 들어 있다.

개발자는 일부분만 보고 그림만 그려서는 안 된다. 제안요청서 곳곳에는 기술 부문을 어떻게 작성해야 하는지 힌트가 숨어 있다.

​

둘째, 논리적 완결성

​

2 고객의 문제 인식과 제안사의 문제 해결 능력

문제 인식과 문제 해결 능력

2-1 경쟁사와 비교하여 제안하라

고객이 문제를 중대하게 생각하고 제안사가 그 문제를 해결할 능력이 탁월하다면 경쟁사와 세부 기능이나 스펙을 비교해서 제안해야 한다.

제안사의 강점을 최대한 부각하는 방법이 경쟁사와 비교하는 것이기 때문이다.

2-2 일단 동감하고 다른 방안을 제시하라

고객이 문제를 중대하게 생각하지만 제안사가 그 문제를 해결할 능력이 미흡하다면 고객의 인식에 일단 동감한 뒤 다른 방안을 제시해야 한다.

문제를 해결할 솔루션을 가진 경쟁사는 자신의 솔루션이 가장 좋은 방안이라고 주장할 것이다.

거기에 대고 솔루션도 없는 제안사가 ‘나도 할 수 있다’, ‘한 번 해보겠다’라고 쓰면 그 프로젝트는 망한다고 봐야 한다.

2-3 고객이 문제를 중대하게 인식하게 만들어라

고객이 사소하게 생각하는 문제를 제안사가 탁월하게 해결할 수 있다고 하자.

그리고 제안사가 내세울 만한 것이 이 문제 해결뿐이라고 하자.

딱히 다른 강점이 없는 상황에 이 문제 해결이 그나마 경쟁사와 비교해서 우위에 설 수 있다고 하자.

그러면 어떻게든 고객이 그 문제를 중대하게 인식하도록 만들어야 한다.

2-4 경쟁사의 전략을 확인해서 대처하라

고객이 문제를 사소하게 생각하고 제안사도 딱히 내세울 만한 솔루션이 없다면 어떻게 할까?

보통은 제안서에 다루지 않거나 다룬다고 해도 평이하게 쓰고 넘어간다.

고객도 신경 쓰지 않고 제안사도 딱히 할 말 없는데 굳이 문제를 장황하게 떠들 필요가 없다.

​

3 고객의 요구사항은 변할 수 밖에 없다

개발은 고객 요구 실현

고객이 요구사항을 처음부터 명확히 하지 않고, 중간에 바꾸고, 막판에 추가하는 이유는 여러 가지가 있다. 그래서 잘 알고 대비해야 한다.

​

요구사항을 분석하지 말고 제시하라

고객은 자기가 원하는 제품이 정확히 뭔지 모른다.

개발자는 고객의 요구사항을 받아서 분석해서 개발하는 것이 아니라, 고객에게 요구사항을 제시해서 고객이 선택하게 만들어야 하고 그 선택에 따라 개발해야 한다.

​

변화하는 요구사항에 대비하라

요구사항은 반드시 변한다.

최초의 요구사항은 단지 참고사항일 뿐이다.

요구사항이 끊임없이 변한다는 것을 이해해야 개발자가 대응할 수 있다.

가장 좋은 방법은 요구사항 정의와 구현, 고객의 검수 사이의 시간 차이를 줄이는 것이다.

​

4 고객의 총 만족도를 높이자

요구라고 다 같은 요구가 아니다

요구사항은 개발자 관점과 고객 관점이 다르다.

가장 좋은 것은 개발자의 시간을 적게 쓰면서도 고객의 만족도가 높은 기능을 먼저 잘 개발하는 것이다.

요구사항을 모두 충족하는 개념이 아니라 고객의 총 만족도를 높이는 것이다.

​

카노 모델로 본 요구의 세 가지 종류

개발자가 시간을 덜 쓰고도 고객의 총 만족도를 높이는 세 가지 패턴을 설명한 카노 모델.

어떤 상품의 기능이나 구성 요소의 충족에 대한 소비자 만족의 관계를 설명한다.

1. 기본 기능은 요구를 충족하지 못하면 고객이 부란족하지만, 요구를 충족했다고 해서 고객 만족도가 크게 오르지는 않는 유형이다.

2. 기능의 성능은 요구를 충족할수록 고객이 만족하고, 충족하지 않으면 고객이 불만족하는 유형이다.

3. 특별한 기능은 고객이 그다지 기대하지 않았던 것이어서 충족하지 못해도 불만족스럽지 않은데, 만약 충족하면 크게 만족하는 경우다.

​

​

7. 기술 블로그 쉽게 쓰고 운영하기

1 기술 블로그를 쉽게 쓰는 방법 3가지

개발자가 기술 블로그를 잘 못 쓰는 이유

블로그에 글을 쓰는 방법이 학생이었을 때 배운 글쓰기 방법과 다르기 때문이다.

주제가 불분명하고 독자 수준이 천차만별이고 딱히 주장할 것이 없는 기술 블로그를 써야 할 때는 생각이 정리되지 않고 목차도 못 잡고 한 줄도 못 쓴다.

​

첫째, 주제 의식을 버리고 소재 의식으로 쓰자

주제 의식이 민족이나 권선징악, 자존감이나 자본주의 같은 추상적 가치를 기반으로 한다면 소재 의식은 특정한 대상이나 상황에 대한 자기 만의 관점이나 생각이나 해결 방안을 뜻한다.

소재 의식은 독자와 상관없이 대상이나 상황에 맞닥뜨렸을 때부터 그 대상이나 상황에서 벗어날 때까지 겪은 일을 담담하게 정리해서 얘기할 뿐이다.

​

둘째, 독자 수준이 아니라 자기 수준으로 쓰자

개발자가 기술 블로그를 쓸 때는 독자를 생각해서 어려운 용어를 일부러 해석해 풀어쓰거나 쉬운 용어로 바꿀 필요가 없다.

원래 사용하는 용어로 그냥 표기하되 필요하다면 용어를 정의한 위키피디아 페이지나 세부 내용을 볼 수 있는 사이트나 문건을 링크로 걸어두면 된다.

기술 블로그란 것을 결국 실력이 비슷한 독자를 위한 것이다.

​

셋째, 재미있게 글을 쓰자

글쓰기 기교는 글을 아름답게 만들고 쉽게 읽히게 한다. 기교를 부리다 보면 글쓰기가 재미있고 글도 재미있어진다.

글에 재미가 있으면 독자가 활발히 반응하고 독자의 반응이 활발하면 블로거는 글을 계속 쓸 동력을 얻는다.

글쓰기 기교는 이렇게 선순환을 만든다.

​

2 글의 종류별로 목차 잡는 법 1

기술 블로그의 4종류, 저, 술, 편, 집

​

저 : 개발기는 목차를 잘 잡아서 본문부터 쓰자

직접 경험하고 실험한 과정이나 결과 (개발기, 도입기, 적용기)

머리말, 본문, 맺음말 중에서 본문을 먼저 쓰고 맺음말, 머리말 순으로 쓰자.

보통 글을 쓸때는 처음부터 쓰려고 한다.

하지만 개발자가 가장 쓰기 어려운 것이 바로 머리말이다.

머리말부터 쓰기 시작하면 한 단락도 못 나가고 쩔쩔매기 일쑤다.

개발자가 가장 잘 쓸 수 있는 내용은 본문이다.

머리말은 맨 마지막에 블로그에 올릴 때 생각나는 대로 간략히 적는 것이 좋다.

​

술 : 원전을 비교하고 실험해 풀이해서 쓰자

어떤 것을 분석하여 의미를 풀이하고 해석한 것 (기술 소개, 용어 분석, 에러 해결 방법 등)

​

3 글의 종류별로 목차 잡는 법 2

편 : 순서를 요약하여 쓰자

산만하고 복잡한 자료를 편집해 질서를 부여한 것 (프로그램 설치/설정 방법, 튜토리얼, 세미나 후기, 책 리뷰)

​

집 : 글쓰기가 두렵다면 자료를 모아 핵심을 엮어서 쓰자

여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것 (명령어 모음, 팁, 00가지 규칙)

​

개발 경험을 다룬 저술은 쓰기가 무척 어렵다.

하지만 개발기는 개발자의 수준을 보여준다.

글을 좀 써 본 개발자라면 개발기에 도전하는 것을 권장한다.

​

4 기업의 기술 블로그 운영 팁

기술 블로그는 회사의 가치를 높인다

1. 채용 직문에 적합하면서 개발 능력이 우수한 개발자 채용에 도움을 준다.
2. 개발 과정에서 생긴 노하우를 체계적으로 축적할 수 있다.
3. 개발자가 스스로 공부하게 만든다.

​

기술 블로그도 투자를 해야 살아난다

회사가 기술 블로그 홍보에 투자하지 않고 개발자의 노력만으로 효과를 보려고 한다면 백발백중 실패한다.

어설프게 시작해서 방문자는 없는데 개발자만 쪼아서 겨우 명맥만 유지하는 기술 블로그라면 애초에 시작하지 않는 것이 좋다.

​

개발자의 글쓰기는 회사의 문화를 반영한다

기업의 기술 블로그는 개인 블로그와 달리 어느 정도 기본 체계를 갖춰야 하고 일정한 수준이 보장돼야 한다.

​

협업해서 글쓰기, 짝 글쓰기를 해보자

1. 글의 완성도가 높아진다.
2. 지식을 보편화할 수 있다.
3. 팀 회고를 할 수 있다.
4. 심리적 안정감을 느낀다.

​

​

회사가 개발자 글쓰기 교육을 하자