Book - 개발자의 글쓰기 / 김철수

개발자의 글쓰기 - 김철수

코딩을 하면서 고민스러웠던 변수 네이밍부터 프로그래머로서 작성해야하는 다양한 방면에서의 글쓰기에 대해 알기 쉽게 알려준다.
한번에 다 체득하기 어려운 내용이라, 필요할 때마다 책을 보며 글쓰기를 해보는 것이 좋겠다.

기본정보

• 위키북스 2019
• 변수 네이밍부터 릴리스 노트, 장애 보고서, 기술 블로그까지 프로그래머의 글쓰기

주요내용

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

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

   • 문장을 쉽게 쓰려면 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 된다.
     ex) 입력 데이터는 3차원 벡터다. 색상 RGB값을 각각 사용하기 때문이다.
   • 서술식, 개조식, 도식의 차이
     • 서술식 : ‘다’로 끝나는 완전한 문장으로 구성된 글.(개발 가이드)
     • 개조식 : 신문의 헤드라인을 쓰거나 어떤 사항을 나열할 때 사용.(릴리스 문서나 장애 보고서)
     • 도식 : 사물의 구조나 관계, 상태를 그림이나 서식으로 보여주는 것.(표, 여러 사항이 유사한 패턴으로 반복될때 )
   • 개조식 서술 방식과 글머리 기호
     • 설명 : 내용을 구체적으로 설명하거나 나열할 때, 하위 요소로 갈수록 부가 설명이 되면서 중요도가 낮아지므로 크기가 작아지고 들여쓰기(※ ◇ ◈ ■)
     • 묘사 : 내용을 그림으로 나타낼 때 그림안에 어떤 요소나 영역을 표시하기 위해서 원형문자를 사용한다.(ⓐ ⓑ ① ②)
     • 논증 : 내용이 논리관계로 구성될때(→ ▷ =)
     • 서사 : 순서나 단계를 나타낼 때(1 2 3 가 나 다)

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

   • 조사, 순서, 숫자, 하다, 기호만 붙이고 나머지는 띄어 쓴다.”

   장애 가 발생 한 지 3 시간 이 지나 버려서 일 단계 대책 이 무의미 하다.
   장애가 발생 한 지 3 시간이 지나 버려서 일 단계 대책이 무의미 하다.(조사 앞에 붙임.)
   장애가 발생 한 지 3시간이 지나 버려서 일단계 대책이 무의미 하다.(숫자, 순서나 단계 뒷낱말과 붙임.)
   장애가 발생한 지 3시간이 지나 버려서 일단계 대책이 무의미하다.(~하다 는 앞 낱말과 붙임.)

   • 문장 부호(비즈니스 문서)
     • 책의 제목이나 신문 이름: 큰따옴표
     • 소제목이나 예술 작품의 제목, 상호, 법률, 규정: 작은따옴표
     • 어떤 내용을 강조하거나 비교해서 드러낼때: 작은따옴표

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

1. 네이밍컨벤션
   • 파스칼 표기법: 모든 단어에서 첫 글자를 대문자로 쓰는 방식(주로 글래스 이름에 사용)
   • 카멜 표기법: 첫 단어를 뺴고 나머지 단어의 첫 번째 글자만 대문자(함수,변수)
   • 상수는 모두 대문자
   • 패키지와 모듈은 모두 소문자
   • BEM 표기법: CSS에서 사용 ‘대상__요소–상태’를 의미
2. 변수 이름을 잘 짓는 법
   • SMART
     • easy to Search 검색하기 쉽고
     • easy to Mix 조합하기 쉽고
     • easy to Agree 수긍하기 쉽고
     • easy to Remember 기억하기 쉽고
     • easy to Type 입력하기 쉽고
3. 주석
   • 이름을 잘지으면 주석을 줄일 수 있다.
   • 주석이 필요한 때도 많다.
   • 주석도 코드다.

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

1. 에러 메시지를 쓰기 전에 에러부터 없애자
   • 친절한 404: 고객센터 연결
   • 깨진 링크는 개발자의 책임
   • 에러 메시지: 개발자용과 사용자용으로 분리
2. 사용자 에러 메시지를 제대로 쓰는 법
   • 에러 메시지를 보여주는 순서
     • 에러내용 - 에러원인 - 에러해결방법
     • 줄 바꿈을 적절히 활용
   • 행동에만 집중하여 오해가 없도록 한다.
3. 사용자 에러를 줄이는 메시지 구조화
   • 버튼 순서 일정하게 한다.
   • 반복 에러시 남은 횟수를 알려준다.
4. 에러 메시지 대신 예방 메시지를 쓰자
   • 에러가 발생하지 않게 비활성화
   • 숫자는 등분하여 알아보기 쉽게
   • 사용자 입장에서 생각한다.

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

1. 체인지 로그를 분류,요약, 종합하는 법
   체인지 로그를 최대한 많이 쓰고,
   • 1단계: 선정하기 (독자가 관심있는것, 노력을 많이 들인것)
   • 2단계: 분류하기 (비슷한 것끼리 묶는다)
   • 3단계: 요약하기
   • 4단계: 종합하기 (전체내용을 한문장으로 정리하여 첫줄에 기입)
2. 체인지 로그는 개발자가 변경한 내용을 적는것이지만, 또한 독자의 관점에서 써야한다.
3. 릴리스 문서는 문제 해결 보고서처럼 작성
   • 문제, 문제점, 해결책, 후속 계획 순으로 작성
   • 법적인 문제를 고려해서 작성
4. 비즈니스를 이해하는 장애보고서 쓰기
   • 질문에 대답하는 신속한 글쓰기 (장애 내용, 영향, 원인, 조치 상황, 결과, 핵심 원인, 향후 대책)
   • 원인과 이유를 찾는 분석적 글쓰기(5whys기법, 근본 원인 파악-사람)
   • 상사를 고려하는 비즈니스 관점의 글쓰기
   • 원하는 것을 얻는 정치적 글쓰기(정확한 단어와 문장으로 현상과 사실을 있는 그대로 표현)

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

1. 서비스 개념을 범주, 용도 특징으로 설명
   • 범주: 독자가 잘 아는 범주를 먼저 말한다.
   • 용도: 그 범주의 용도를 말한다.
   • 특징: 유사 서비스와 차별화하는 특징을 말한다.(장점, 강점)
2. 정확히 이해하도록 그림과 글로 묘사
   • 그림과 사진, 화살표등
   • 요구사항정의서는 객관적 묘사만 포함
   • 기획자나 디자이너를 위해 주관적 묘사에도 익숙해야함
3. 논증으로 유용한 정보를 제공
   • 근거를 댄다
   • 거칠게도 공손하게도 쓰지 않는다
   • 주장과 이유의 거리를 좁혀서 쓰자
4. 서사를 활용해 목차를 만들자
   • 스크린숏에 번호를 넣어 한 문장씩 글을 쓰는 방식
   • 글이 많지 않은 경우에는 한 문자응로 요약하고 단어 앞에 번호를 붙인다
   • 순서에서 단계를 단계에서 목차를 만든다

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

생략

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

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

   • 주제의식을 버리고 소재 의식으로 쓰자
   • 독자 수준이 아니라 자기 수준으로 쓰자
   • 재미있게 글을 쓰자

2. 글의 종류별로 목차 잡는 법 - 저술

   • 저: 직접 경험하고 실험한 과정이나 결과(개발기,도입기,적용기)
     술: 어떤 것을 분석하여 의미를 풀이하고 해석한 것(기술 소개,용어 분석, 에러 해결 방법)
     편: 산만하고 복잡한 자료를 편집해 질서를 부여한 것(프로그램 설치 방법, 튜토리얼, 세미나 후기)
     집: 여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것(명령어 모음, 팁)
   • 저(개발기)는 목차를 잘 잡아서 본문부터 쓰자
   • 술) 원전을 비교하고 실험해 풀이해서 쓰자

3. 글의 종류별로 목차 잡는 법 - 편집

   • 편) 순서를 요약하여 쓰자
   • 집) 글쓰기가 두렵다면 자료를 모아 핵심을 엮어서 쓰자