개발자의 글쓰기

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

오직 개발자를 위한 글쓰기의 모든 것을 담았습니다!

이 책은 개발자의 글쓰기 능력을 종합적으로 향상하기 위한 책이다. 코드 안에서는 함수와 변수 이름을 짓는 것부터 주석 쓰는 법, 에러 메시지 쓰는 법까지 알려준다. 코드 밖에서는 릴리스 노트, 장애 보고서, 개발 가이드를 어떻게 하면 잘 쓸 수 있는지를 알려준다. 외주 개발을 하는 개발자를 위해 SI 제안서의 기술 부문을 설득력 있게 쓰는 법도 놓치지 않았다. 블로그를 운영하려는 개발자나 IT기업을 위해 기술 블로그를 쓰는 법과 운영하는 팁도 담았다.

 

도서 상세 이미지

김철수

한양대 국문과를 졸업하고 개발자, 기획자, 컨설턴트, 강사 등으로 불리며 벤처에서 대기업까지 다양한 회사와 직종에서 20년을 일했다. 코오롱 그룹 IT계열사 코오롱베니트㈜에서 공공 SI 프로젝트 PM도 하고 에너지 관리 솔루션도 개발하고 코오롱그룹의 “Industry 4.0 동향보고서” 편집장도 했다. 그 전에는 벤처기업 ㈜프리챌에서 아이템사업부장으로 일했고, 텍스트 분석 솔루션을 개발하는 스타트업 등에서 서비스를 기획하고 개발했다. 그때 첫 책으로 웹2.0과 서비스 기획을 다룬 『싸이월드는 과연 다음을 넘어섰을까?』를 출간했다. 지금은 모바일 퀴즈 애플리케이션과 콘텐츠 큐레이션 서비스를 개발해 운영하면서 AI 기반 실내 환기 알고리즘을 연구하고 있다. 개발 중에 틈틈이 글을 써서 인공지능 시대에 생각의 생산성을 높이는 방법을 다룬 『생각경영법』과 『팀장을 위한 보고서 검토 기술』 같은 책도 썼다. 비즈니스 글쓰기, 테크니컬 라이팅, 디지털 역량, 신사업 기획을 주제로 강의와 컨설팅을 하고 서울창의혁신투어 프로그램도 만들어 진행한다.

  • ▣ [프롤로그] 개발자의 글쓰기는 달라야 한다
    • 개발자는 글을 못 쓴다?
    • 개발자 글쓰기의 특징: 정확성, 간결성, 가독성
    • 개발자의 글쓰기
    •  
  • ▣ 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 기업의 기술 블로그 운영 팁
      • 기술 블로그는 회사의 가치를 높인다
      • 기술 블로그도 투자를 해야 살아난다
      • 개발자의 글쓰기는 회사의 문화를 반영한다
      • 협업해서 글쓰기, 짝 글쓰기를 해보자
    •  
  • ▣ [애필로그] 회사가 개발자 글쓰기 교육을 하자
  • 22쪽, 페이지 상단 예제 코드의 2번째 줄

    if (m.monthAndDay >= todayMonthAndDay){
    

    ==>

    if (m.monthAndDay <= todayMonthAndDay){
    
  • 22쪽, 페이지 하단 예제 코드의 9번째 줄

    if (m.monthAndDay >= todayMonthAndDay){
    

    ==>

    if (m.monthAndDay <= todayMonthAndDay){
    
  • 54쪽, 밑에서 4번째 줄

    표기법은 ‘대상--요소__상태’를 의미한다.

    ==>

    표기법은 ‘대상__요소--상태’를 의미한다.