[도서] 개발자의 글쓰기

 

 

• ▣ [프롤로그] 개발자의 글쓰기는 달라야 한다
  개발자는 글을 못 쓴다?
  개발자 글쓰기의 특징: 정확성, 간결성, 가독성
  개발자의 글쓰기
  
  ▣ 1장: 개발자가 알아야 할 글쓰기 기본
  01 문장과 단락을 구조화하는 법
  ___문장을 구조화하는 법
  ___서술식, 개조식, 도식의 차이
  ___개조식 서술 방식과 글머리 기호
  ___단락을 구조화하는 위계
  02 쉽게 쓰는 띄어쓰기와 문장 부호
  ___가장 쉬운 띄어쓰기 원칙
  ___오해하기 쉬운 문장 부호(큰따옴표, 작은따옴표)
  03 영어 단어 선택과 외래어 표기법
  ___비슷한 듯 다른 듯, 단어 선택
  ___외산 제품 표기와 외래어 표기법
  
  ▣ 2장: 개발 시간을 줄여주는 이름 짓기와 주석 쓰기
  01 네이밍 컨벤션, 이유를 알고 쓰자
  ___개발자의 가장 큰 고민은 이름 짓기
  ___이름 짓기는 창조가 아니라 조합
  ___코드의 네이밍 컨벤션은 영어 표기법을 상속받았다
  ___파스칼 표기법으로 클래스 이름 짓기
  ___카멜 표기법으로 함수?변수의 이름 짓기
  ___상수는 모두 대문자로 쓴다
  ___패키지와 모듈은 모두 소문자로 쓴다
  ___BEM 표기법
  ___가독성과 소통이 먼저다
  02 변수 이름을 잘 짓는 법
  ___i는 변수 이름이지만 d는 아니다
  ___긴 이름? 짧은 이름? 검색 잘 되는 이름!
  ___복수형을 나타내는 s를 붙일까 말까?
  ___약어를 쓰는 것이 좋을까? 안 쓰는 것이 좋을까?
  ___중요한 단어를 앞에 쓴다
  ___함수 이름 짓는 순서
  03 좋은 이름의 기준, SMART
  ___한 번에 좋은 이름을 지을 수는 없다
  ___좋은 이름이 가진 5가지 특징
  ___easy to Search: 검색하기 쉽게 이름 짓는 법
  ___easy to Mix: 조합하기 쉽게 이름 짓는 법
  ___easy to Agree: 수긍하기 쉽게 이름 짓는 법
  ___easy to Remember: 기억하기 쉽게 이름 짓는 법
  ___easy to Type: 입력하기 쉽게 이름 짓는 법
  04 좋은 코드에는 주석이 없다?
  ___이름을 잘 지으면 주석을 줄일 수 있다
  ___처음부터 주석 없이 코딩하는 연습을 하자
  ___주석이 필요한 때도 많다
  05 다른 개발자를 배려하는 주석 쓰기
  ___코드는 의미를, 주석은 의도를
  ___주석의 반복
  ___주석의 발췌와 요약
  ___주석도 코드다
  
  ▣ 3장: 사용자와 소통하는 에러 메시지 쓰기
  01 에러 메시지를 쓰기 전에 에러부터 없애자
  ___친절한 404, 불친절한 404
  ___404 에러가 죄송할 일인가?
  ___깨진 링크는 개발자의 책임이다
  ___개발자용 에러 메시지와 사용자용 에러 메시지를 분리하자
  02 사용자 에러 메시지를 제대로 쓰는 법
  ___사용자 에러에 대처하는 메시지
  ___에러 메시지를 보여주는 순서
  ___오락가락 메시지와 버튼 메시지
  03 사용자의 에러를 줄이는 메시지 구조화
  ___버튼의 순서
  ___사용자의 반복 에러를 막는 법
  04 에러 메시지 대신 예방 메시지를 쓰자
  ___서비스를 이해하면 에러를 예방할 수 있다
  ___사용자를 이해하면 에러를 예방할 수 있다.
  ___닭이 먼저? 알이 먼저?
  
  ▣ 4장: 독자 관점에서 릴리스 문서와 장애 보고서 쓰기
  01 체인지 로그를 분류, 요약, 종합하는 법
  ___체인지 로그의 양과 만족도의 관계
  ___1단계: 선정하기
  ___2단계: 분류하기
  ___3단계: 요약하기
  ___4단계: 종합하기
  02 고객에게 유용한 정보를 쓰자
  ___개발자 관점과 고객 관점
  ___과거를 리뷰하고 미래를 보여주자
  ___Semantic Versioning(유의적 버전)
  03 릴리스 문서는 문제 해결 보고서처럼 쓰자
  ___문제와 문제점을 구별하자
  ___문제, 문제점, 해결책, 후속 계획 순으로 적자
  ___법적인 문제를 고려해서 쓰자
  04 비즈니스를 이해하는 장애 보고서 쓰기
  ___장애 보고서의 특징
  ___질문에 대답하는 신속한 글쓰기
  ___원인과 이유를 찾는 분석적 글쓰기
  ___상사를 고려하는 비즈니스 관점의 글쓰기
  ___원하는 것을 얻는 정치적 글쓰기
  
  ▣ 5장: 설명, 묘사, 논증, 서사로 개발 가이드 쓰기
  01 서비스 개념을 범주, 용도, 특징으로 설명하자
  ___범주, 용도, 특징
  ___범주를 정확하고 적절하게 선택하자
  ___용도를 범주의 핵심 기능으로 기술하자
  ___특징을 장점과 강점에서 뽑아 쓰자
  02 정확히 이해하도록 그림과 글로 묘사하자
  ___글에 묘사를 더하면 이해가 빠르다
  ___글과 그림의 내용을 일치시키자
  ___객관적 묘사와 주관적 묘사 둘 다 하자
  03 논증으로 유용한 정보를 제공하자
  ___의견을 쓰려면 근거를 대자
  ___거칠게도 공손하게도 쓰지 말자
  ___주장과 이유의 거리를 좁혀서 쓰자
  ___문제와 답의 거리를 좁혀서 쓰자
  04 서사를 활용해 목차를 만들자
  ___개발과 서사
  ___독자의 수준 대신 기술의 범용성을 기준으로 쓰자
  ___순서에서 단계를, 단계에서 목차를 만들자
  
  ▣ 6장: 수주를 돕는 SI 제안서 쓰기
  01 개발자가 알아야 할 제안서 작성 원칙
  ___개발자와 제안 PM의 차이
  ___시스템 구성도의 본질은 그림이 아니다
  ___첫째, 제안요청서 분석
  ___둘째, 논리적 완결성
  02 고객의 문제 인식과 제안사의 문제 해결 능력
  ___문제 인식과 문제 해결 능력
  ______① 경쟁사와 비교하여 제안하라
  ______② 일단 동감하고 다른 방안을 제시하라
  ______③ 고객이 문제를 중대하게 인식하게 만들어라
  ______④ 경쟁사의 전략을 확인해서 대처하라
  03 고객의 요구사항은 변할 수밖에 없다
  ___개발은 고객 요구 실현
  ___요구사항을 분석하지 말고 제시하라
  ___변화하는 요구사항에 대비하라
  04 고객의 총 만족도를 높이자
  ___요구라고 다 같은 요구가 아니다
  ___카노 모델로 본 요구의 세 가지 종류
  
  ▣ 7장: 기술 블로그 쉽게 쓰고 운영하기
  01 기술 블로그를 쉽게 쓰는 방법 3가지
  ___개발자가 기술 블로그를 잘 못 쓰는 이유
  ______첫째, 주제 의식을 버리고 소재 의식으로 쓰자
  ______둘째, 독자 수준이 아니라 자기 수준으로 쓰자
  ______셋째, 재미있게 글을 쓰자
  02 글의 종류별로 목차 잡는 법 I - 저술
  ___기술 블로그의 4종류, 저, 술, 편, 집
  ______저: 개발기는 목차를 잘 잡아서 본문부터 쓰자
  ______술: 원전을 비교하고 실험해 풀이해서 쓰자
  03 글의 종류별로 목차 잡는 법 II - 편집
  ______편: 순서를 요약하여 쓰자
  ______집: 글쓰기가 두렵다면 자료를 모아 핵심을 엮어서 쓰자
  04 기업의 기술 블로그 운영 팁
  ___기술 블로그는 회사의 가치를 높인다
  ___기술 블로그도 투자를 해야 살아난다
  ___개발자의 글쓰기는 회사의 문화를 반영한다
  ___협업해서 글쓰기, 짝 글쓰기를 해보자
  
  ▣ [애필로그] 회사가 개발자 글쓰기 교육을 하자

---

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

체인지로그는 회사의 공식발표이며, 독자와 직접 소통하는 문건

 

• 1단계 : 선정하기 

		개발자가
		노력 많이	노력 적게
독자가	관심 o	1순위	2순위
	관심 x	3순위	삭제

 

• 2단계 : 분류하기
  • 공개할 체인지 로그를 선정 후 비슷한 유형끼리 묶기
    • - 개발관점에서 묶기
    • - 사용자관점에서 묶기 (보다 디테일한 설명으로 변화된 내용을 구체적으로)

• 3단계 : 요약하기
  • - 서술식을 개조식으로 글 다듬기 

• 4단계 : 종합하기
  • - 릴리스 전체 내용을 종합하여 한 문장으로 만들고 로그 첫 줄에 요약기입

 

 

"기억보단 기록을"이라는 말처럼, 개발자에게 글쓰기는 중요한 스킬 중 하나로 생각한다.
나 또한 이 블로그를 통해 배운 것을 기록하고 있다.

개발자로서 기술을 습득하고 사용하는 것만큼이나 그것을 다른 이들에게 전달하는 능력도 중요하다 판단된다.

나의 글이 누군가에게 도움이 될 수 있다면, 더욱 가치있는 글이 되기 때문이다. 

그래서 나는 내가 쓴 글이 다른 사람들에게 어떻게 받아들여질지에 대해 항상 고민이다. 

또한, 나는 글을 쓸 때 명료하고 알기 쉽게 전달하고 싶다. 

비록 전문적이고 심도 있는 기술을 담을 수 없을지라도, 나만의 이야기를 명확하게 전달하고 싶었다.

내가 고민한 흔적과 풀어간 문제들

책을 읽고 난 후, 개발자로서의 글쓰기에 대한 이해가 더욱 깊어졌다. 

내가 쓴 글이 더욱 명확하고 전달력이 있도록 수정하고자 개선할 것이다. 

---