글을 잘 쓰고 싶다는 생각을 계속해왔고, 더욱 능숙한 글쓰기를 위한 지식을 쌓으려고 이 책을 읽게 되었습니다.

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

문장을 구조화 하는 방법

문장을 쉽게 쓰기 위해서는 간단한 문장을 구조로 핵심을 말한 뒤, 필요에 따라 부가 설명을 하면된다.

예시) 입력데이터는 3차원 벡터다. 색상 RGB 값을 각각 사용하기 때문이다.

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

1) 서술식
'~다'라고 끝나는 완전한 문장으로 구성된 글
줄거리가 있는 설명이나 이야기라면 서술식 사용

2) 개조식
종결 어미 대신 명사(예: 완료, 증대 등)나 용언의 명사형(예: ~했음)으로 끝나는 글
서술식에서 강조가 필요한 내용이라면 개조식 사용
개조식을 사용할때 글머리 기호를 꼭 써야함

3) 도식
주로 표(예:테이블, 그래프, 차트 등) 를 의미
각 항목이나 사항의 관계를 명확히 규정하고 싶다면 도식 사용

네이밍 규칙

• 클래스는 파스칼 표기법 사용
• 함수, 변수는 카멜표기법 사용
• 상수는 모두 대문자 사용
• 패키지와 모듈은 모두 소문자 사용

변수 이름 잘 짓는 법

1) 배열 인덱스를 i,j,k로 적거나 x,y좌표를 x, y로 표현하는 것은 관습적이다. 그렇기 때문에 이상하지 않다.
하지만, day를 d로 표기하거나 아무런 의미 없는 글자를 변수로 쓰는것은 좋지 않다.

2) 긴 이름, 짧은 이름이 중요하기 보다는 검색이 잘되는 이름을 사용해야 한다.

3) 복수형에 s를 붙이기보다는 'Array'나 'list of'를 사용하는 것이 났다.

4) 보편적인 약어는 사용하는 것이 좋다. (예: HTML, VIP, temp, param 등)

5) 중요한 단어를 앞에 쓴다.

좋은 이름의 기준, SMART

• easy to Search 검색하기 쉽고
• easy to Mix 조합하기 쉽고
• easy to Agree 수긍하기 쉽고
• easy to Remember 기억하기 쉽고
• easy to Type 입력하기 쉽고

좋은 코드에는 주석이 없다.

1) 이름을 잘 지으면 주석을 줄일 수 있다.

//스크린 최대 높이
int h = 480

=>

int screenHeightMax = 480

2) 처음부터 주석 없이 코딩하는 연습을 하자

TIP!!! 'is' 접두사 자체가 true아니면 false를 반환하는 것을 의미

3) 주석이 필요할 때도 많다.

• 개발자의 영어 실력이 부족하다면 추가적인 설명이 쓰는것이 도움이 된다.

다른 개발자를 배려하는 주석 쓰기

1) 코드는 의미를, 주석은 의도를 담아야한다.
주석 다음과 같은 의도가 담겨야 한다.

• 이유를 알려주는 것
• 개발자가 새롭게 발견한 것
• 예상 질문과 답
• 할 일이나 주의, 개선 아이디어를 주는 것
• 다른 사람에게 보완을 요청하는 것
• 개발자의 속마음을 표현하는 것

2) 반복되는 주석
반족되는 주석이 코드를 길게 만들고 가독성을 느끼게 할 수도 있지만, 상황에 따라 필요할 수도 있다. 그렇기 때문에 주석을 무조건 줄여야 하는 것은 아니다.

3) 주석의 발췌와 요약

4) 주석도 코드다.
주석은 디버깅이 되지 않는다. 그렇기 때문에 잘못된 주석이 있어도 발견하기가 쉽지가 않고, 발견하더라고 오타구나 하고 넘어가게 된다. 하지만 주석도 잘 쓰면 도움이 되기 때문에 꼼꼼하게 다뤄야 한다.

사용자와 소통하는 에러 메세지 쓰기

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

1) 친절한 404, 불친절한 404
보통 404 에러는 사용자가 URL을 잘못 입력했거나, 링크를 클릭했으나, 해당 페이지가 없을 때 마주하게 됩니다.
이 때, 오류만 설명하기 보다는 고객센터 페이지나 다른 페이지로 넘어갈 수 있도록 도움을 줄 수 있다.

2) 깨진 링크는 개발자의 책임이다.
깨진 링크를 눌러 사용자가 해당 페이지가 없는 경우는 없어야 한다.

3) 개발자용 에러 메세지와 사용자용 에러 메세지를 분리하자

사용자 에러 메세지 제대로 쓰는 법

1) 사용자 에어에 대처하는 메세지
사용자에게 에러 메세지를 보여주는 이유는 사용자 스스로 에러를 해결하게 하는 것이다. 따라서 사용자 에러 메세지에는 에러의 내용, 에러의 원인, 에러 해결 방법이 포함돼야 한다.

예시) 
에러 내용: 회원가입을 진행할 수 없습니다.
에러 원인: 휴대전화 번호를 잘못 입력하셨습니다.
에러 해결 방법: 휴대전화 번호 입력란에는 숫자만 입력하십시오.

2) 에러 메세지를 보여주는 순서
에러의 내용, 에러의 원인, 에러 해결 방법 순서를 반드시 지키기 보다는 상황에 맞게 순서를 바꾸면 더 좋은 에러 메세지가 되는 경우도 있다.

3) 오락가락 메세지와 버튼 메세지
버튼의 본래의 역할은 특정한 행동을 유도하는 것이다. 따라서 버튼 메세지를 분명히 표시하는 것이 좋다.

사용자의 에러를 줄이는 메세지 구조화

1) 버튼의 순서
Os마다 확인-취소의 순서가 다르다. 정해진 표준이 없기때문에 사용자 경험이 어긋나게 만드는 요인이 될 수 있다. 그렇기 때문에 구체적인 행동을 적거나 시각적으로 강조하는 것이 좋은 방안이 될 수 있다. 그리고 회사가 원하는 방향으로 유도하면 된다.

2) 사용자 반복 에러를 막는 법
예를 들어, 사이트에 로그인할 때 특정횟수가 틀리면 자동입력방지를 보여주는 방식으로 사용자의 반복되는 에러를 막을 수 있다.

에러 메세지 대신 예방 메세지를 쓰자

1) 서비스를 이해하면 에러를 예방할 수 있다.
서비스에 대한 이해를 통해서 에러를 발생시키는 동작을 막아 사전에 예방할 수 있다.

2) 사용자를 이해하면 에러를 예방할 수 있다.

3) 닭이 먼저? 알이 먼저?
재확인 방식: 결재 요청 -> 재확인 -> 결재처리
취소 방식: 결재 요청 -> 결재처리+취소기능
혼합 방식: 결재 요청 -> 재확인 -> 결재처리+취소기능
혼합 방식처럼 사용자가 자신의 행동을 주체적으로 책임지게 만들어야 한다.

위의 방법 중에 어떤 방법을 사용할 지는 서비스와 사용자에 따라 달라지겠지만, 개발자도 자신만의 철학을 가지고 사용자가 에러메세지를 어떻게 받아들일지 생각해봐야한다.

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

체인지 로그의 양과 만족도의 관계

체인지로그를 작성하지 않으면 일을 하지 않는 것처럼 보이게 된다. 그렇다고 너무 많이 적게되면 다 읽으려고 하지 않는다. 그렇기 때문에 일정한 기준으로 선정하고 비슷한 것끼리 분류한 뒤 문장을 요약하는 기술이 필요하다.

• 1단계: 선정하기
• 2단계: 분류하기
• 3단계: 요약하기
• 4단계: 종합하기

1단계 선정하기

위의 표와 같이 확실한 기준을 만들면 공개할 체인지 로그 순위를 좀 더 전략적으로 선정할 수 있다.

2단계 분류하기

공개할 체인지 로그를 선정했으면 비슷한 체인지 로그끼리 묶어야 한다.

1) 개발 관점에서 비슷한 작업으로 묶는 방법

• 새로운 기능 추가
• 기능 개선
• 오류 수정

2) 사용자 관점에서

• 게임 준비
• 게임 중
• 게임 종료

3단계 요약하기

불필요한 부사, 형용사, 조사, 어미를 없애고, 정확하고 적절한 개조식 문장으로 요약하기

4단계 종합하기

각각의 문장에서 핵심이 되는 것을 발췌하여 종합문장을 개조식으로 만든다.

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

1) 개발자 관점과 고객 관점

체인지 로그를 보는 사람이 누구이냐를 생각하며 작성해야 한다. 사용자의 관점과 개발자의 관점은 다르다. 문제를 해결함으로써 사용자의 관점에서 해결되는 문제가 무엇인지 알아야 한다.

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

3) Semantic versioning

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

1) 문제와 문제점을 구별하자

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

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

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

장애 보고서의 특징
첫째, 장애 보고서는 개발자가 원할 때 쓸 수 없다.
둘째, 장애의 1차 원인은 대부분 다른 원인의 결과다.
셋째, 장애 보고를 받는 윗사람은 대부분 개발자가 아니다.
넷째, 장애를 해결했다고 해서 100% 해결한 것은 아니다.

1) 질문에 대답하는 신속한 글쓰기

2) 원인과 이유를 찾는 분석적 글쓰기

문제 해결 기법 중에 5whys를 사용하여 원인을 찾는다.

3) 상사를 고려하는 비즈니스 관점의 글쓰기

4) 원하는 것을 얻는 정치적 글쓰기

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

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

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

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

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

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

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

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

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

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

1) 의견을 쓰려면 근거를 대자

2) 거칠게도 공손하게도 쓰지 말자
사용자에게 여지를 주는 말은 사용하지 않는다. 너무 공손한 표현을 쓰면 사용자를 가이드할 수 없게 된다.

~ 하십시오.
~ 하지 마십시오. 

와 같은 표현을 사용합니다.

3) 주장과 이유의 거리를 좁혀서 쓰자
주장을 말했으면 이유를 바로 말한다.

4) 문제와 답의 거리를 좁혀서 쓰자
개발자 문서는 문제 해결 문서이므로 문제 다음에 답이 먼저 나와야 한다.

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

서사는 사실을 있는 그대로 순서대로 적는 것을 말한다.
개발에서는 서사는 어떤 일을 하라고 지시하는 것이다. 글만 있는 소설이 아니라 그림이나 사진이 글과 붙어 있는 잡지처럼 글을 써야 한다.

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

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

수주를 돕는 SI 제안서 쓰기

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

1) 제안 요청서 분석
개발자가 제안 요청서에서 힌트를 잘 찾아내기만 하면 기술 부문을 더 전략적으로 쓸 수 있다.

2) 논리적 완결성
제안서는 기승전결이 있는 소설이 아니다. 그 누구도 제안서를 소설 읽듯이 처음부터 읽지 않는다.하나의 항목에 그 항목에 대한 내용을 논리적으로 납득시킬 수 있는 내용이 들어있어야한다.

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

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

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

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

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

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

개발은 고객의 요구사항을 실현하는 것이다.

1) 요구사항을 분석하지 말고 제시하라
고객은 자기가 원하는 제품이 정확히 뭔지 모른다. 개발자는 고객의 요구사항을 받아서 분석해서 개발하는 것이 아니라 고객에게 요구사항을 제시해서 고객이 선택하게 만들어야 하고 그 선택에 따라 개발해야 한다.

2) 변화하는 요구사항에 대비하라
요구사항은 반드시 변한다. 가장 좋은 방법은 요구상항 정의와 구현, 고객의 검수 사이의 시간차이를 줄이는 것이다. 특정 기능이 개발이 끝나면 즉시 고객에세 테스트를 요청하고 검수를 받는다.

고객의 총 만족도를 높이자

1) 요구라고 다 같은 요구가 아니다.
개발자는 고객의 총 만족도를 높이는 쪽으로 설계해야 한다. 개발자의 소요 시간과 고객의 예상 만족도를 숫자로 표시하여 총 만족도를 높이는 개발을 할 수 있도록 한다.

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

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

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

1) 주제 의식을 버리고 소재 의식으로 쓰자

2) 독자 수준이 아니라 자기 수준으로 쓰자
독자에게 모든 걸 다 설명하기 보다는 스스로 공부할 수 있는 링크를 남기는 것이 더 좋다.
나와 비슷한 수준 독자들을 위한 것이다.

3) 재미있게 글을 쓰자

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

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

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

목차를 먼저 정하고 본문을 쓴다. 그리고 본문을 쓰고 나면 맺음말을 쓴다. 머리말을 마지막에 블로그에 올릴 때 생각나는 대로 간략히 쓴다.

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

본래의 내용을 바탕으로 자기 생각이나 분석, 해설을 덧붙이는 방식을 쓰는데 좋다.

3) 편: 순서를 요약하여 쓰자

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

기업의 기술 블로그 운영 팁

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

기업이 기술 블로그를 운영하는 이유

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

2) 기술 블로그도 투자를 해야 살아남는다.
기술블로그를 홍보 매체로 생각해야 한다.

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

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

짝 글쓰기는 두 명이 글 하나를 같이 쓰는 방식이다.

짝 글쓰기의 좋은 점은

첫째, 글의 완성도가 높아진다.
둘째, 지식을 보편화할 수 있다.
셋째, 팀 회고를 할 수 있다.
넷째, 심리적 안정감을 느낀다.

짝 글쓰기 방법으로는

• Drive & Navigator: 한 명은 글 쓰고 다른 한 명은 글을 검토한다.
• Coder & Advisor: 한 명은 글 쓰고 다른 한 명은 조언을 한다.
• Verbalizer & Listener: 글을 쓰고 난 뒤 한 명은 글을 읽고, 다른 한 명은 귀로 듣는다.
• Ping-Pong : 두 명이 번갈아 가면서 글을 쓰는 방식이다.

후기

글을 잘 쓰고 싶다는 생각에서 이 책을 읽게 되었다. 책을 읽으면서 중요하다고 생각되는 부분만 적으면서 읽었다. 꽤 많은 양이지만, 책에 있는 내용에 비하면 아주 적은 내용이다. 위의 내용중에 관심이 있는 내용이 있다면 책을 직접 읽어보는 것을 추천한다. 읽으면서 배울 점이 많은 책이다. 개인적으로는 대상 독자들을 생각하며 글을 쓰는 것이 가장 중요한 포인트라고 생각된다. 이 책을 읽었다고 해서 글 쓰는 능력이 많이 향상 될 것이라고 생각하지는 않는다. 글은 많이 써봐야 실력이 향상된다고 생각한다. 나도 계속 글을 쓰는 연습을 할 것이다. 글을 쓸일이 있을 때마다 많은 도움을 받을 수 있는 책이라고 생각되기 때문에 개발자라면 한번쯤 읽어 보는 것을 추천한다.

출처

• 개발자의 글쓰기
  저자 : 김철수
  출처 : 위키북스