기획자나 관리자의 글쓰기에 논리력, 설득력, 실행력이 중요하다면, 개발자의 글쓰기에는 정확성, 간결성, 가독성이 중요하다. … 정확성은 틀림이 없이 확실한 것을 말한다. … 간결성은 글에 군더더기가 없고 간단하고 깔끔한 것을 말한다. … 가독성은 쉽게 읽히는 것을 말한다. … 정확성을 높이면 간결성과 가독성이 낮아진다. 간결성을 높이면 정확성과 가독성이 낮아진다. 가독성이 높아지면 간결성과 정확성이 낮아진다.
-p20 ~ p21
요즘은 개발자가 다른 개발자나 사용자, 잠재 고객과 소통하는 일이 잦아졌다. 깃허브등을 통해 개발자가 만든 코드를 공개하고, 개발자 사이트를 통해 외부 개발자와 협력하는 일도 늘었다. 그러다 보니 개발하는 것만큼 글 쓸 일이 많아졌다.
-p23 ~ p24
개발자가 알아야 할 글쓰기 기본
1. 색상 RGB 값을 사용하기 때문에 입력 데이터는 3차원 벡터다.
2. 입력 데이터는 색상 RGB 값을 각각 사용하기 때문에 3차원 벡터다.
3. 입력 데이터는 색상 RGB 값을 각각 사용한다. 그래서 입력 데이터는 3차원 벡터다.
4. 입력 데이터는 3차원 벡터다.
5. 입력 데이터는 3차원 벡터다. 색상 RGB 값을 각각 사용하기 때문이다.
-p26 ~ p27
개발자의 생각을 글로 표현하는 데는 크게 세 가지 방법이 있다.
첫째는 서술식이다. 서술식은 바로 앞의 문장처럼 ‘~다’로 끝나는 완전한 문장으로 구성된 글을 말한다. 무엇을 설명하거나 논증할 때 주로 사용하는 방식이다. 소설이나 신문 기사처럼 개발 가이드 문서는 대부분 서술식으로 쓴다.
둘째는 개조식이다. 개조식은 신문의 헤드라인을 쓰거나 어떤 사항을 나열할 때 사용한다. 행사의 개요를 적을 때 일자, 장소, 참가자 등을 종결 어미(예: ~다) 대신 명사(예: 완료, 증대 등)나 용어의 명사형(예: ~했음)으로 끝내는 것을 개조식이라 한다. 주로 릴리스 문서나 장애 보고서를 쓸 때 개조식으로 쓴다.
셋째는 도식이다. 도식은 사물의 구조나 관계, 상태를 그림이나 서식으로 보여주는 것이다. 이때 가장 간단한 형태의 도식은 행과 열로 이뤄진 표다. 행렬에 글만 있으면 표라 하고, 막대 같은 그림이 있으면 도표라고 한다. 여기서 도식은 주로 표를 의미한다. … 줄거리가 있는 설명이나 이야기라면 서술식으로 써야 한다. 여러 가지 종류의 항목과 내용이 반복되거나 서술식에서 강조가 필요한 내용이라면 개조식으로 써야 한다. 각 항목이나 사항의 관계를 명확히 규정하고 싶다면 도식으로 써야 한다. … 글을 개조식으로 쓸 때는 글머리 기호를 꼭 써야 한다. … 이런 기호는 모두 쓰임새가 달라서 적절하게 사용해야 한다. … 말머리 기호의 쓰임새는 글의 진술 방식으로 나뉜다. 글의 진술 방식은 설명, 묘사, 논증, 서사의 네 가지가 있다.
설명: 내용을 구체적으로 설명하거나 나열할 때 ■, □, ○, ※, ㆍ 등을 사용한다. 하위 요소로 갈수록 부가 설명이 되면서 중요도가 낮아지므로 크기가 작아지고 들여 쓰기를 해야 한다. 묘사: 내용을 그림으로 나타낼 때 그림 안에 어떤 요소나 영역을 표시하기 위해서는 ⓐ, ① 등의 원형문자를 사용한다. 논증: 내용의 논리관계(귀납, 연역, 인과, 유추, 비교, 단계 등)로 구성될 때는 ∴, →, ☞, >, = 등을 사용한다. 서사: 순서나 단계를 나타날 때는 1, 2, 3, 가, 나, 다 등 숫자나 문자를 사용한다.
-p28 ~ p30
개발자가 한글 문서를 쓸 때 가장 어려워하는 것 중 하나가 띄어쓰기다.
-p35
조사, 순서, 숫자, 하다, 기호만 붙이고 나머지는 띄어 쓴다.
비즈니스 문서에서 따옴표의 용도는 조금 다르다. 우선 책의 제목이나 신문 이름을 나타내는 겹낫표와 겹화살괄호 대신에 큰따옴표를 쓴다. 소제목이나 예술 작품의 제목, 상호, 법률, 규정 등을 나타낼 때 쓰는 홑낫표와 홑화살괄호 대신에 작은따옴표를 쓴다. 어떤 내용을 강조하거나 비교해서 드러내야 할 때 작은따옴표를 쓰기도 한다.
-p39
정확한 단어를 쓰는 것도 중요하지만 그보다 더 중요한 것은 얼마나 일관성 있고 개연성 있게 쓰느냐다. … 프로그램 안에서 일관성과 개연성만 있다면, 또는 그 프로그램의 코드를 보는 개발자 사이에 일관적이고 개연적인 합의만 돼 있다면 어떻게 쓰든 상관없다. … 영어를 한글로 쓰고 말할 때 지켜야 할 것은 외래어 표기법이 아니라 일관성이다. 한 문서 안에서만 통일한다면 굳이 어색한 외래어 표기법에 짜맞추지 않아도 된다.
-p43 ~p44
개발 시간을 줄여주는 이름 짓기와 주석 쓰기
아무리 작은 프로그램이나 간단한 애플리케이션이라도 수 많은 이름을 지어야 한다. … 서비스 기획자는 서비스 이름 하나만 지으면 되고 마케터는 마케팅 메시지 한 줄만 잘 만들면 되지만, 개발자가 만들어야 할 이름은 수십, 수백 가지다. 어쩌면 개발자가 가장 힘들어하는 일이 이름 짓기일지도 모른다. … 모든 개발자는 자기 코드를 읽는 사람이 주석 없이도 금방 코드를 이해하게 코드를 작성하고 싶어 한다. 함수가 어떤 일을 하는지 이름만 보고도 짐작하게 만들고 싶어 한다. 그러면서도 간결하고 명료하며 일관성을 가진 이름을 갖고 싶어 한다. 하지만 현실은 그렇지 못하다.
-p47
클래스는 파스칼 표기법, 함수나 변수는 카멜 표기법, 상수는 모두 대문자로 쓴다. 패키지와 모듈은 모두 소문자로 쓴다.
-p50 ~ p54
대문자를 쓰든 소문자를 쓰든, 하이픈을 쓰든 언더스코어를 쓰든 중요한 것은 표기법 자체가 아니라 그렇게 쓰는 이유다. 그동안 수많은 개발자가 이렇게 컨벤션을 만든 이유는 가독성과 소통 때문이다. 코드를 읽기 쉽게 만들고 다른 개발자와 소통하기 위해서다. … 하지만 가독성이 높다고 소통이 더 잘 되는 것은 아니다. 소통이 잘 되려면 서로가 같은 컨벤션을 지켜야 한다. … 따라서 같은 부서의 개발자, 또는 하나의 프로그램과 관련된 개발자들끼리는 코딩하기 전에 기본적인 컨벤션 규칙을 정하는 것이 우선이다. 그래야 가독성과 소통이라는 두 마리 토끼를 동시에 잡을 수 있다.
-p55
패키지, 클래스, 모듈, 함수, 변수를 망라해 좋은 이름인지를 확인하는 5가지 기준을 SMART로 정했다.
easy to Search: 검색하기 쉽고 easy to Mix: 조합하기 쉽고 easy to Agree: 수긍하기 쉽고 easy to Remember: 기억하기 쉽고 easy to Type: 입력하기 쉽고
-p65
사용자와 소통하는 에러 메시지 쓰기
개발자용 에러 메시지와 사용자용 에러 메시지를 분리해 작성하는 것이 좋다.
-p99
에러 메시지의 목적은 사용자에게 에러가 났음을 알려주는 것이 아니라 사용자 스스로 에러를 해결하게 하는 것이다. 따라서 사용자 에러 메시지에는 에러의 내용, 에러의 원인, 에러 해결 방법이 포함돼야 한다. 에러 내용: 오류로 인한 문제와 종류 에러의 원인: 오류를 발생시킨 직접적이고 근본적인 원인 에러 해결 방법: 사용자가 오류를 해결할 가장 쉽고 빠른 방법
-p102
확인 취소 문제, 페이스북은 ‘취소-나가기’ 순서인데 크롬 브라우저는 ‘나가기-취소’ 순서다. 따라서 확인, 취소 대신 구체적은 행동을 적는 것도 좋은 방법이다.
-p107 ~ p110
모든 개발자는 사용자가 에러 없이 프로그램을 사용하게 만들고 싶어 한다. 하지만 에러가 한 번도 발생하지 않게 프로그램을 온전히 개발할 수 있는 개발자는 없다. … 그래서 에러를 줄이려면 개발자도 사용자의 사용 방식을 이해해야 한다. 사용자가 어떻게 사용할지를 충분히 이해하고 조사하고 분석해야 에러를 줄일 방법을 찾을 수 있다.
-p113
독자 관점에서 릴리스 문서와 장애 보고서 쓰기
어떤 일을 하고 나서 그 일의 내용을 상사나 고객에게 글로 보고해야 할 때가 있다. 이때 글을 지나치게 줄여 쓰면 일을 안한 것처럼 보인다. 그렇다고 해서 일의 내용을 하나씩 구체적으로 다 쓰면 아무도 읽지 않는다. 체인지 로그가 이런 경우에 해당한다. 간단히 쓰면 할 일이 없어 보이고 자세히 쓰면 아무도 읽지 않아 쓸모가 없다.
-p120
체인지 로그의 양을 줄이려면 체인지 로그 중에서 쓸 것과 없앨 것을 구분하는 기준이 필요하다.
-p123
체인지 로그는 개발자가 변경한 내용을 적은 것이다. 하지만 체인지 로그를 보는 독자는 뭔가 새로운 것, 바뀐 것, 그래서 자기에게 좋거나 유익하거나 어떤 행동을 해야 할지 명확하게 지시하는 것을 보고 싶어 한다. … 외부 개발자나 일반 사용자가 보는 체인지 로그를 쓸 때는 개발자 관점이 아니라 고객 관점에서 써야 한다.
-p132
IT 분야에서 장애는 대부분 재발한다. 재발하는 원인은 시스템 자원이 늘 부족하기 때문이기도 하지만, 대부분 사람의 문제다. 한쪽에서 새로운 프로그램으로 바꿨는데, 그와 연관된 다른 쪽에서는 모르고 있다가 장애가 난다.
-p154
의사결정을 내리려면 아랫사람에게 정확한 정보를 들어야 하는데, 아랫사람이 보카시 장난으로 말을 하면 의사결정을 할 수 없다. 그래서 개발자는 좀 더 정치적으로 확정해서 말할 필요가 있다.
-p161
설명, 묘사, 논증, 서사로 개발 가이드 쓰기
서비스 매뉴얼이나 개발 가이드의 첫 문단은 서비스 개념을 설명하는 자리다. 독자가 첫 문단에서 서비스 개념을 확실히 잡지 못하면 이후에 나오는 내용을 제대로 이해할 수 없다. 개발자가 독자에게 서비스 개념을 설명할 때는 범주, 용도, 특징 순으로 쓰는 것이 좋다.
-p164
범주는 서비스를 소개하거나 설명하는 첫 문장인 만큼 정확하고 적절하게 정해야 한다.
-p167
용도는 독자가 이 서비스를 이용하는 이유다. 독자가 서비스 매뉴얼이나 개발 가이드를 읽는 이유는 서비스의 핵심 기능을 사용하기 위해서다. 따라서 서비스의 핵심 기능을 쓰면 용도를 기술할 수 있다.
-p169
범주와 용도에는 보편적인 내용을 적는다. 하지만 특징은 차별화하는 내용을 적어야 한다. 개발자에게 차별화는 서비스의 장점과 강점이다. 장점은 자기 기준에서 잘하는 것이고, 강점은 경쟁 서비스와 비교해서 나은 것이다.
-p171
수주를 돕는 SI 제안서 쓰기
개발은 고객의 요구사항을 실현하는 것이다. 그런데 요구사항이 처음부터 끝까지 모호한 경우가 많다. 개발하는 중에 요구사항이 바뀌기도 하고, 새로운 요구사항이 들어오기도 하고, 힘들게 개발한 기능이 요구사항에서 빠지디고 한다. … 고객이 요구사항을 처음부터 명확히 하지 않고, 중간에 바꾸고, 막판에 추가하는 이유는 여러 가지가 있다. 그래서 그 이유를 잘 알고 대비해야 한다.
-p220
개발자가 고객의 요구를 충족하지 못하면 고객의 불만이 커진다. 그러면 개발자가 고객의 요구를 충족하면 고객은 무조건 만족하는가? … 가장 좋은 것은 개발자의 시간을 적게 쓰면서도 고객의 만족도가 높은 기능을 먼저 잘 개발하는 것이다.
-p226
기술 블로그 쉽게 쓰고 운영하기
소재 우선 글쓰기는 주제 의식이 아니라 소재 의식을 갖고 쓰는 것이다. 주제 의식이 민족이나 권선징악, 자존감이나 자본주의 같은 추상적 가치를 기반으로 한다면 소재 의식은 특정한 대상이나 상황에 대한 자기만의 관점이나 생각이나 해결 방안을 뜻한다. … 주제 의식은 많은 사람에게 보편적인 주제를 선택해서 더 많은 사람에게 주제 의식을 퍼뜨리는 것이지만, 소재 의식은 독자와 상관없이 대상이나 상황에 맞닥뜨렸을 때부터 그 대상이나 상황에서 벗어날 때까지 겪은 일을 담담하게 정리해서 얘기할 뿐이다.
