BookReview [개발자의 글쓰기]

읽은 기록

개발자의 글쓰기

개발관련 글을 자주 작성하면서 개인적으로 글쓰기 실력이 조금 부족하다고 생각해서 읽게된 책이다. 짧고 가벼워서 이동중이나 매주 토요일에 참여하는 모각코에서 읽었다.

내용은 당장 읽어도 활용하기 힘든 내용도 있었고, 지금 당장 도움이 되는 내용도 많았다. 읽기 전에는 사실 클린코드나 좋은 코드, 나쁜 코드와 같은 내용에서 중복이 많을 것 같다고 생각했는데 읽어보니 생각보다 다른 내용이 많았다.

결론적으로는 만족스러웠던 책이다! 개발자로 살아가며 글을 써야할 때 도움이 될 것 같다.

프롤로그: 개발자의 글쓰기는 달라야 한다

개발자는 글을 못 쓴다?

글을 정말 잘 쓰는 학습자는 군더더기를 다 없애고 핵심만 남겨 간결하게 쓴다.

금도끼 은도끼 이야기

• 나무꾼, 연못에 도끼 유실
• 산신령, 금/은/소도끼 제시
• 나무꾼, 쇠도끼만 인정
  산신령, 금/은도끼 포상

여기서 개발자의 시각으로 바라본다면 나무꾼, 산신령, 도끼는 반복된다. 따라서 다음과 같이 수정될 수 있다.

금도끼 은도끼 이야기 [W=나무꾼, G=산신령, x=도끼]

• W, 연못에 x 유실
• G, 금/은/쇠x 제시
• w, 쇠x만 인정
• G, 금/은x 포상

이 글을 다시 읽으면 바로 개발자가 쓴 글이라는 것을 알 수 있다. 기획자나 관리자의 글쓰기에 논리력, 설득력, 실행력이 중요하다면, 개발자의 글쓰기에는 정확성, 간결성, 가독성이 중요하다.

사례가 극단적이긴 하지만, 개발자의 글쓰기는 정확성, 간결성, 가독성이 중요하다.

개발자 글쓰기의 특징: 정확성, 간결성, 가독성

요즘은 개발자 중에 블로거가 많아서 개발과 관련된 게시물이 있는데, 이런 글들은 정확하고 간결하며 가독성이 높아야 한다. 나도 블로그를 운영중이지만, 정말 과거에 비해 많이 발전했다고 생각한다. 그래도 이 책을 읽고 더 개선될 점이 많이 보일 것 같다.

정확성은 틀림이 없이 확실한 것을 말한다. 글로 쓰인 대로만 개발하면 버그없이 실행돼야 한다. 간결성은 글에 군더더기가 없고 간단하고 깔끔한 것을 말한다. 구구절절 설명하는 것이 아니라 핵심만 써야 한다. 가독성은 쉽게 읽히는 것을 말한다. 쉬운 용어를 사용하고 필요하다면 표나 그림으로 잘 정리해야 한다.

문제는 이 세 가지 원칙이 서로 대치한다는 데 있다. 정확성을 높이면 간결성과 가독성이 낮아지고 나머지 2개도 서로 대치한다는 성질이 있다. 따라서 기본적으로 트레이드오프의 이념을 가지고 있어야 한다.

개발자의 글쓰기

그렇다고 정확하고 간결하고 가독성이 높은 글을 쓸 수 없는 것은 아니다. 누구나 꾸준하게 공부하며 연습하면 좋은 글을 작성할 수 있다.

그러나 지난 수십 년 동안 개발 방법과 개발 도구는 엄청나게 발전했지만, 개발자의 글쓰기 실력은 그다지 나아진 것 같지 않다. 테크니컬 라이터가 따로 있지 않는 한 개발자가 개발 문서를 작성하는 경우가 많은데 많이 어려워한다.

대부분의 개발 공부는 코딩관련 지식이 주를 이루기 때문에 개발자의 글쓰기 방법은 배울 수 없다. 최근 개발문화는 깃헙을 통한 오픈소스, 개발자들간의 협력이 중요시되어 개발만큼 글을 작성해야 하는 일이 많아졌다.

이 책은 이러한 개발자의 글쓰기 능력을 종합적으로 향상하기 위한 책이다. 코드 안에서는 함수와 변수 네이밍, 주석, 에러 메시지, 릴리스 노트, 장애 보고서, 개발 가이드, 블로그 작성법 등을 작성하는 방법들을 다룬다.

코딩과 마찬가지로 글쓰기도 과학이고 기술이다. 누구나 체계적으로 배우기만 하면 글을 잘 쓸 수 있다.

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

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

문장을 구조화하는 법

문장을 만드는 방법은 여러 가지다. ‘나는 김철수다’와 같이 ‘주어+서술어’가 가장 기본이지만 ‘김철수가 사랑하는 사람은 이소연이 아니다.’처럼 ‘주어+보어+서술어’로 확장되기도 한다. 그런데 이 문장은 ‘이소연은 김철수가 사랑하는 사람이 아니다.’처럼 주어절과 보어를 교체할 수 있다.

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

이 문장을 쓰려면 머릿속에 ‘색상 RGB 값을 사용한다.’와 ‘입력 데이터는 3차원 벡터다.’를 떠올린 다음 두 문장의 관계를 연결하는 것까지 생각해야 한다. 이렇게까지 생각해서 문장을 만드려면 시간과 수고가 많이 든다.

따라서 문장의 주어인 ‘입력데이터’를 문장의 처음으로 뺄 수 있다.

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

이 문장은 인과관계가 있는 복문이므로 두 문장으로 나눌 수 있다. 복문이란 두 개 이상의 절(주어와 술어를 포함하는 문장 단위)을 포함한 문장

입력 데이터는 색상 RGB 값을 각각 사용한다. 그래서 입력 데이터는 3차원 벡터다.

이 문장을 쓰려면 머릿속에서 본인이 잘 아는 내용, 즉 ‘입력 데이터는 3차우너 벡터다’를 떠올리고 바로 쓴다. 그럼 다음과 같은 문장이 만들어진다.

입력 데이터는 3차원 벡터다.

이제 입력 데이터가 3차원 벡터인 이유를 어떻게 설명할 것인지를 결정하면 된다. 색상은 보통 RGB의 세 값을 사용하므로 그래픽을 조금이라도 이해한다면 당연히 3차원 벡터를 알 것이기에 ‘입력 데이터는 3차원 벡터다’라고만 써도 충분할 것이다.

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

문장을 쉽게 쓰려면 이처럼 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 된다. 이때 첫 문장의 주어를 가져다가 소제목으로 만들면 자연스럽게 문단이 구성할 수 있다.

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

개발자의 생각을 글로 표현하는 데는 크게 세 가지 방법이 있다.

첫째는 서술식이다. 서술식은 바로 앞의 문장처럼 ‘~다’로 끝나는 완전한 문장으로 구성된 글을 말한다. 무엇을 설명하거나 논증할 때 주로 사용하는 방식이다. 소설이나 신문 기사처럼 개발 가이드 문서는 대부분 서술식으로 쓴다.

둘째는 개조식이다. 개조식은 신문의 헤드라인을 쓰거나 어떤 사항을 나열할 때 사용한다. 행사의 개요를 적을 때 일자, 장소, 참가자 등을 종결 어미 대신 명사나 용언의 명사형(‘~했음’)으로 끝내는 것을 개조식이라고 한다. 주로 릴리스 문서나 장애 보고서를 쓸 때 개조식으로 쓴다.

셋째는 도식이다. 도식은 사물의 구조나 관계, 상태를 그림이나 서식으로 보여주는 것이다. 이때 가장 간단한 형태의 도식은 행과 열로 이뤄진 표다. 행렬에 글만 있으면 표라고 하고, 막대 같은 그림이 있으면 도표라고 한다. 여기서 도식은 주로 표를 의미한다.

“00 메신저에는 4가지 푸시 알림이 있습니다. 공지 알림은 서비스 변경이나 장애, 이벤트 등 메신저 운영사가 직접 보냅니다. 오전 9시부터 오후 6시 사이에만 발송합니다. 메시지 알림은 등록된 친구가 메시지를 보냈을 때 자동으로 시스템이 전송합니다. 친구 등록 알림은 새로운 친구가 등록되었을 때 알려줍니다. 친구 해제 알림은 친구가 탈퇴했을 때 알려줍니다.”

이렇게 여러 사항이 유사한 패턴으로 반복될 때는 다음과 같이 개조식으로 쓰는 것이 보기도 좋고 이해하기도 쉽다.

• 공지 알림: 서비스 변경이나 장애, 이벤트
  • 메신저 운영사가 오전 9시부터 오후 6시 사이에 직접 발송
• 메신저 알림: 등록된 친구가 메시지를 보냈을 때 시스템이 자동으로 전송
• 친구 등록 알림: 새로운 친구가 등록되었을 때
• 친구 해제 알림: 친구가 탈퇴했을 때

전보다는 훨씬 명확하고 이해하기 좋지만 개조식 표현에는 중복과 누락이 있음을 알 수 있다. 메신저 알림, 친구 등록 알림, 친구 해제 알림은 모두 시스템이 자동으로 전송한다(중복). 하지만 친구 등록 알림과 해제 알림으 누가 전송했는지 알 수 없다. 이 때 내용을 도식(표)로 표현하면 더 분명하게 드러낼 수 있다.

알림 종류	상황	발송 방식	발송 시간
공지	서비스 변경, 장애, 이벤트	운영사(수동)	오전 9시 ~ 오후 6시
메시지	등록된 친구가 메시지 전송	시스템(자동)	제한 없음
친구 등록	새로운 친구 등록	시스템(자동)	제한 없음
친구 해제	친구 탈퇴	시스템(자동)	제한 없음

가장 중요한 점은 내용과 형식이 일치해야 한다는 것이다. 줄거리가 있는 설명이나 이야기라면 서술식으로 써야 한다. 여러 가지 종류의 항목과 내용이 반복되거나 서술식에서 강조가 필요한 내용이라면 개조식, 각 항목이나 사항의 관계를 명확히 규정하고 싶으면 도식을 사용하면 된다.

개조식 서술 방식과 글머리 기호

글을 개조식으로 쓸 때는 글머리 기호를 꼭 써야 한다. 글머리 기호는 네모, 동그라미, 점, 막대를 비롯해 숫자 화살표까지 다양하다. 이런 기호는 쓰임새가 모두 달라서 적절하게 사용해야 한다. 쓰임새를 무시하고 아무렇게나 사용한다면 말머리 기호 체계가 무너져서 독자가 이해하기 어렵다.

• 설명: 내용을 구체적으로 설명하거나 나열할 때 ■, ▢, ○, ▪, ※등을 사용한다. 하위 요소로 갈수록 부가 설명이 되면서 중요도가 낮아지므로 크기가 작아지고 들여쓰기를 해야 한다.
• 묘사: 내용을 그림으로 나타낼 때 그림 안에 어떤 요소나 영역을 표시하기 위해서는 ①, ④, ⑦등의 원형문자를 사용한다.
• 논증: 내용이 논리관계(귀납, 연역, 인과, 유추, 비교, 단계 등)로 구성될 때는 →, >, ›, ∵, ∴, = 등을 사용한다.
• 서사: 순서나 단계를 나타낼 때는 1, 2, 3, 가, 나 등 숫자나 문자를 사용한다.

단락을 구조화하는 위계

비즈니스 문서에는 문단과 문단 사이에 위계가 있어야 한다. 비즈니스 문서에 위계가 없으면 비즈니스 문서가 아니라 소설이 된다. 이때 위계는 위치와 계층을 합한 말이다.

위치는 2차원 평면 좌표를 말하며, 전 직원이 사진을 찍는다고 하면 보통 사장이 가운데에 위치한다. 회의실도 출입구에서 먼 곳에서 부터 높은 직급이 앉곤 한다. 문서도 마찬가지로 급이 낮은 문장은 더 들여쓰기를 함으로 위치를 맞춘다.

계층은 3차원 입체의 높이를 뜻한다. 무대는 객석보다 항상 높다. 높은 곳의 의자는 낮은 곳의 의자보다 크고 고급스럽다. 문서에서 계층은 굵기, 모양, 밑줄, 줄 간 거리 등으로 표현한다.

개발자가 사용하는 개발 툴은 예문의 위치는 맞출 수 있지만 계층은 맞출 수 없다. 따라서 개발자가 일반 문서를 작성할 때 위치는 과도하게 맞추지만, 계층은 거의 표현하지 않는다. 컴퓨터 개발자의 코드를 처음부터 순서대로 읽으면서 순식간에 체계를 잡아낸다.

하지만 사람은 계층이 표현되지 않은 문서를 보면서 체계를 잡아내기 매우 어렵다. 계층이 없는 문서를 읽고 이해하는 데 시간이 더 걸리고 오해도 자주 생긴다. 그래서 비즈니스 문서에는 반드시 계층을 표현한다. 계층을 표현하면 문서의 체계를 먼저 이해할 수 있으므로 읽는 시간이 덜 걸린다.

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

가장 쉬운 띄어쓰기 원칙

개발자가 한글 문서를 쓸 때 가장 어려워하는 것 중 하나가 띄어쓰기다. 영어는 독립적인 낱말이 모여 문장을 만들어 내지만, 한글은 문장마다 달라질 수 있다.

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

• 장애 가 발생 한 지 3 시간 이 지나 버려서 일 단계 대칙 이 무의미 하다( v.1.1.0 )

이 문자에서 조사는 모두 앞 낱말에 붙인다.

• 장애가 발생 한 지 3 시간이 지나 버려서 일 단계 대책이 무의미 하다. ( v.1.1.0 )

코딩에서는 조사와 비슷한 것이 쉼표다. 쉼표는 앞 낱말에 붙어야 한다.

auto obj = {
    arg1: 1,
    arg2: 2,
    arg3: 3
};

일, 이, 삼과 같은 한글 숫자가 순서나 단계를 나타낼 때는 뒤 낱말과 붙인다.

• 장애가 발생 한 지 3 시간이 지나 버려서 일단계 대칙이 무의미 하다. ( v.1.1.0 )

숫자는 모두 뒤 낱말과 붙인다.

• 장애가 발생 한 지 3시간이 지나 버려서 일단계 대책이 무의미 하다. ( v.1.1.0 )

‘~하다’는 모두 앞 낱말과 붙인다.

• 장애가 발생한 지 3시간이 지나 버려서 일단계 대책이 무의미하다. ( v.1.1.0 )

마지막으로 기호는 모두 앞 낱말과 붙인다.

• 장애가 발생한 지 3시간이 지나 버려서 일단계 대책이 무의미하다 (v.1.1.0)

함수를 선언할 때 함수 이름 끝에 괄호를 쓰고 그 안에 인수를 쓰는데, 이때도 붙여 쓴다. wordSpacing(arg1, arg2, arg3);

띄어쓰기를 좀 더 꼼꼼하게 보고 싶다면 맞춤법 검사기를 추천한다.

오해하기 쉬운 문장 부호(큰따옴표, 작은따옴표)

개발 언어마다 문장 부호의 용도와 의미가 조금씩 다르다. 그래서 개발자 사이에서 문장 부호의 쓰임새를 두고 격론이 벌어질 때도 있다.

그 중에서 따옴표는 더욱 언어마다 상이하다. C언어에서는 작은 따옴표는 단일 문자에 사용하고 큰 따옴표는 문자열에 사용한다. 자바스크립트에서는 큰 따옴표와 작은 따옴표를 모두 문자열에 사용한다.

한글에도 따옴표 규정이 있다. 큰 따옴표는 직접 대화를 표시하거나 말이나 글을 인용할 때 사용한다. 작은 따옴표는 인용한 말 안에 있는 인용한 말, 또는 마음속으로 한 말을 쓸 때 사용한다.

하지만 비즈니스 문서에서 따옴표의 용도는 조금 다르다. 우선 책이나 제목이나 신문 이름을 나타내는 겹낫표와 겹화살표<>대신에 큰 따옴표를 사용한다.

• 이번에 출간된 “개발자의 글쓰기”를 참고했음.

소제목이나 예술 작춤의 제목, 상호, 법률, 규정 등을 나타낼 때 쓰는 홋낫표, 홑화살괄호 대신에 작은 따옴표를 사용한다. 또한 어떤 내용을 강조하거나 비교하기 위해서 드러내야 할 때도 작은 따옴표를 사용한다.

• 이번 프로젝트의 이름은 ‘안드로이드’로 정했음.
• 중요한 것은 ‘창의’가 아니라 ‘열정’임

영어 단어 선택과 외래어 표기법

비슷한 듯 다른 듯, 단어 선택

개발을 하다 보면 반대되는 영어 단어를 선택해야 할 때가 많다. 예를 들어 hide라는 단어로 감추기로 표시했다면 반대로 show로 정확히 사용해야 한다. hide 대신 invisiable을 쓰면 안된다. invisiable의 반대말은 visiable이기 때문이다.

반대말이 있으면 비슷한말도 있다. 비슷한말은 서로 의미는 비슷하지만 개발에서 사용하는 의도는 다르다. 예를 들어 중단이라는 의미를 가진 영어 단어로는 stop, end, finish, pause, suspend, hold 등이 있다. stop은 잠시 중단 하는 것이어서 언제든 재시작할 수 있다. 완전히 중단되어서 재시작할 가능성이 없다면 end를 써야 한다. finish는 끝장을 본 상태여서 재시작을 고려할 필요도 없다. pause는 아주 잠시 일시적으로 중단된 것이어서 금방이라도 다시 시작할 것 같은 상황이다. suspend는 다음 단계의 시작을 중단한 것이고 hold는 어떤 의도가 있어서 중단한 것이다.

이외에도 get, return, set 등 비슷하면서 완전히 다른 의미를 가지는 영어단어가 많기 때문에 개발자는 주의해서 선택해야 한다.

수정을 나타내는 change, modify, revise도 의도가 다른 말이다. change는 내용을 단순히 바꾸는 것이다. modify는 잘못된 것을 바로잡을 때 쓴다. revise는 기존에 없던 새로운 정보나 아이디어를 덧붙여 기존 내용과 달라졌음을 분명히 할 때 사용한다.

parameter는 매개변수로, 함수에 정의한 변수를 뜻하고 argument는 전달 인자로, 함수를 호출할 때 전달되는 값을 의미한다.

must와 should는 우리말로 ‘~해야 한다’라고 번역되만 의미가 다르다. must는 반드시 해야 하는 것이고 should는 권장하는 것이다.

외산 제품 표기와 외래어 표기법

일관성 있게 써야 하는 것 중에서 가장 대표적인 것이 외산 제품 표기다. 예를 들어 Windows 10을 보면 제품의 공식적인 이름은 ‘Windows 10’이다. 하지만 우리말로 쓸 때는 여러 표현들이 나오기도 한다.

• 윈도우 10
• 윈도우즈 10
• 윈도 10

개발자에게 친숙한 릴리즈, 릴리스와 같은 표현이나 파이썬도 마찬가지다. 확실하게 말하자면 글쓰기에서 지켜야할 것은 외래어 표기법이 아니라 일관성이다. 따라서 한 문서 안에서만 통일한다면 굳이 어색한 외래어 표기법에 짜맞추지 않아도 된다.

“이미 굳어진 외래어는 관용을 존중하되, 그 범위와 용례는 따로 정한다.”

느낀점

인터넷에서 책을 구매하기 전 여타 다른 책에서 다루는 코드 작성법에 대한 내용이 많을 것 같아서 걱정했지만 걱정과 달리 내가 필요로 했던 내용이 많아서 순식간에 읽은 것 같다.

저자가 한국인+개발자라 개발자들이 글쓰기를 어려워 하는 이유에 대한 명확한 분석과 글을 잘써야 하는 이유 그리고 가장 많이 하는 실수를 중심으로 챕터를 잘 나눠서 설명해주신 것 같다.

책을 읽고 글로 많이 정리하는 편이라 알게 모르게 2년전과 비교해서 글을 작성하는 솜씨나 구사력이 좋아졌다고 생각했는데, 그것이 왜 그런지를 적절한 정의와 단어로 설명이 되어서 이해할 수 있었다.

특히 문장을 구조화하는 법의 내용은 내가 쓴 글이 복잡하다면 꼭 다시 읽어볼 생각이다.

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

네이밍 컨벤션, 이유를 알고 쓰자

개발자의 가장 큰 고민은 이름 짓기

개발자는 한 프로젝트만 해도 매우 많은 내용의 이름을 지어야 한다. 애플리케이션 이름부터 변수 이름까지 방대한 양의 이름을 작성해야 함은 틀림없다. 실제로 개발자 커뮤니티의 조사 결과에 따르면 이름짓기가 가장 어려운 테크닉으로 뽑힌 바도 있다.

자기 코드에 주석을 주렁주렁 달고 싶은 개발자는 없을 것이다. 따라서 명확하고 간결한 네이밍으로 주석을 달지 않아도 자신이 하려는 말을 잘 전달할 수 있는 네이밍이 필요하지만, 현실은 그렇지 못하다. 왜 그렇게 이름을 지었는지도 기억이 나지 않고 결국 코드를 다 뜯어봐야 기억이 나는 경우가 태반이다.

이름 짓기는 어렵긴 하지만 잘만 하면 코드를 짜기도 쉽고 이해하기도 쉽다. 다른 개발자와 소통하기도 쉬워지고, 공개할 경우 외부 개발자에게 인정도 받는다. 또한, 요즘과 같이 애자일처럼 문서를 최소화한다면 더욱더 필수인 기술이다.

이름 짓기는 창조가 아니라 조합

딱 말하자면 이름 짓기는 무에서 유를 창조하는 것이 조합적인 성격을 가진다. 실제로 깃허브의 인기 자바 소스를 분석한 결과 클래스, 함수, 변수 이름의 명명 특징을 연구한 결과 다음과 같은 중요한 네이밍 규칙을 데이터로 증명했다.

• 자바 네이밍 컨벤션을 철저히 준수한다.
  • 클래스는i UpperCamelCase
  • 함수와 변수는 LowerCamelCase
  • 상수는 UPPER_DELIMITER_CASE
• 네이밍은 보통 16글자, 3단어를 조합한다.
  • 클래스 네임: 3.18 단어
  • 함수 네임: 3.36 단어
  • 변수 네임: 2.57 단어
• 품사는 주로 명사, 동사, 형용사의 조합이다.
  • 명사 + 명사 + 명사
  • 동사 + 명사 + 명사
  • 형용사 + 명사 + 명사 등

코드의 네이밍 컨벤션은 영어 표기법을 성속받았다

네이밍 컨벤션은 기본적으로 영어 표기법을 준수한다.

• 중요하거나 크거나 특정한 것을 가리키거나 제목에 해당하는 명사는 모두 첫 글자를 대문자로 쓴다.
• 그런 명사들이 이어질 때는 첫 글자를 모두 대문자로 쓴다.
• 명사나 관사가 나닌 동사, 형용사 등은 소문자를 쓴다.

이 특성은 코딩에 그대로 적용된다. 그래서 파스칼, 카멜 표기법 등이 만들어졌다.

파스칼 표기법으로 클래스 이름 짓기

파스칼 표기법은 첫 글자를 대문자로 쓰는 방식이다. 주로 클래스 이름에 해당하며 그 이유는 클래스가 프로그래밍에서 가장 주요하고 높은 위치에 있고, 고유명사처럼 특정되기 때문이다. 인터페이스도 마찬가지

카멜 표기법으로 함수, 변수의 이름 짓기

카멜 표기법은 첫 단어를 빼고 나머지 단어의 첫 번째 글자만 대문자로 쓴다. 주로 함수나 변수에 사용한다. 함수는 동작을 시키는 명령어 개념이므로 첫 단어가 주로 동사다. 변수는 형용사로 시작하는 경우도 많다.

상수는 모두 대문자로 쓴다

영어 표기 원칙에서는 상수를 대문자로 쓰지 않는다. 하지만 프로그래밍에서는 값이 변해서는 안된다는 점을 강조하고 주의시키기 위해 가독성을 높이는 방법으로 대문자를 선택한 것이다. 요즘은 IDE가 발달하여 상수에 대한 경고나 다름을 잘 표시해주지만 통일성은 가지는 것이 좋다.

패키지와 모두 소문자로 쓴다

패키지와 모듈은 분명히 클래스나 함수보다 더 높은 위치다. 그러므로 패키지 이름과 모듈 이름은 당연히 대문자로 써야 할 것 같다. 하지만 실제로는 소문자로만 쓴다.

이것은 패키지와 모듈이 클래스를 모으거나 함수를 담아두는 통에 불과하기 때문이다. 클래스가 책이라고 하면 패키지는 전집이라고 볼 수 있다. 인식하고 구별하는 것은 각각의 책이지 전집이 아니다. 전집은 단지 책을 모아놓은 것에 불과하다.

BEM 표기법

CSS에서 사용하는 BEM표기법은 ‘대상__요소–상태’를 의미한다. 대상의 요소나 부분을 의미할 때는 언더스코어 두 개로 연결하고 대상이나 요소의 상태나 송석을 의미할 때는 하이픈 두 개로 연결한다.

가독성과 소통이 먼저다

대문자를 쓰든 소문자를 쓰든, 하이픈을 쓰든 안쓰든 가장 중요한 것은 소통 때문이다. 코드를 읽기 쉽게 만들고 다른 개발자와 소통하기 위해서다. 남들이 으레 그렇게 하니 따라 할 것이 아니라 그렇게 쓰는 이유를 알고 써야 한다.

이 이야기는 통일성이 왜 필요한지, 협업에서 같은 메타모델을 공유하는 것에 대한 중요성과 연관된다고 생각한다.

변수 이름을 잘 짓는 법

i는 변수 이름이지만 d는 아니다

가장 많이 쓰는 변수 이름은 i, Log, result였다. 사실 i는 정수를 뜻하는 integer와 지수를 뜻하는 index의 첫 글자로 간주되므로, 개발자가 반목문의 카운터나 배열의 인덱스로 많이 사용한다. 따라서 i, j, k의 흐름은 어색하지 않다.

마찬가지로 x, y를 통해 좌표를 나타내는 것도 이상하지 않지만 a나 b와 같은 아무런 의미가 없는 글자를 변수로 쓰는 것은 좋지 않다. 일자 day를 사용하고 싶다면 그냥 day를 쓰면 된다.

긴 이름? 짧은 이름? 검색 잘 되는 이름

소프트웨어 초창기 개발에서는 IDE도 뛰어나지 않고 용량도 제한적이라 굳이 변수 이름을 길게 지어서 오타를 낼 확률을 높이지 않았다. 하지만 요즘은 개발 환경이 매우 좋기 때문에 접두어를 붙이거나 약어를 사용할 필요가 없다. 따라서 명확하고 검색이 잘 되는 이름으로 네이밍을 해야 한다.

복수형을 나타내는 s를 붙일까 말까?

이 부분도 통일된 컨벤션을 따라가는 것이 좋지만, -s가 중간에 있을 땐 알아보기 힘들다. 따라서 중간에는 array나 list of를 쓰는 편이 좀 더 나을 수도 있다.

약어를 쓰는 것이 좋을까? 안 쓰는 것이 좋을까?

약어를 쓰는 것 또한 팀 내의 컨벤션을 따라가는 것이 좋지만, 어느정도 선을 지켜가며 사용하는 것이 좋다. 과도한 약어 사용은 코드를 더 어렵게 만들기 때문이다.

약어를 만드는 좋은 방법은 보편성을 기준으로 정하는 것이다. User Interface는 UI라고 표기하고, User Experience는 UX라고 쓴다.

중요한 단어를 앞에 쓴다

변수 이름을 여러 단어로 조합할 때는 순서를 잘 정해야 한다. 예를 들어 총 방문자 수를 나타내는 변수를 보통 totalvisitor로 그대로 번역해 변수로 사용하곤 한다. 하지만 이 변수를 사용할 때는 total로 검색하기보다 visitor로 검색하는 경우가 더 많을 것이다.

따라서 visitor를 앞에 쓸 것을 추천한다. 물론 요즘 개발 도구는 검색할 때 해당 단어가 포함된 클래스나 변수를 다 찾아주기 때문에 의미가 없을 수 있지만, 정렬된 결과를 위해 컨벤션을 지키는 것도 중요하다.

함수 이름 짓는 순서

함수 이름을 지을 때 처음에는 한글 문장에서 시작해서 몇 개의 영어 단어 조합으로 끝내는 경우가 많다. 이는 컨텍스트와 함수가 가지는 행위의 복잡성을 줄이는 작업을 통해 함수이름을 지어야 한다.

이 부분은 함수 자체가 얼마나 많은 일을 감당하고 있는지와 연괸된다.

좋은 이름의 기준, SMART

한 번에 좋은 이름을 지을 수는 없다

책의 공기인형의 사례와 같이 어떤 시점에서 바라보느냐에 따라 이름이 달라질 수 있다. 결국 앞에서 말한 내용과 같이 흔들리지 않는 보편성을 기준으로 이름을 지어야 한다. 그렇다고 스트레스까지 받을 필요없이 한 번에 완성할 수 없는 사실을 인정하자.

좋은 이름이 가진 5가지 특징

좋은 이름을 정하는 기준은 제각각이지만, 좋은 이름이 가지는 공통의 기준은 있다.

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

easy to Search: 검색하기 쉽게 이름 짓는 법

검색하기 쉬운 이름은 고전적 범주화를 이용해 한 단계 상위 범주의 이름을 태그처럼 덧붙이면 된다. 고전적 범주화란 특정한 대상을 묶어 상위 범주를 만들어 이해하는 것이다. 예를 들어 소나무, 감나무, 배나무 같은 개별적인 대상을 나무라는 이름으로 범주화해서 이해한다. 그러면 어떤 나무를 보고 그 이름을 몰라도 일단 나무라고 인식하기 때문에 나무로 시작할 수 있다.

주의할 점은 같은 접두어를 가진 함수나 변수의 개수가 너무 많으면 안 붙이는 것만 못하다.

easy to Mix: 조합하기 쉽게 이름 짓는 법

가장 좋은 방법은 개발 언어의 문법과 조합하여 이름을 짓는 것이다. 개발 언어 자체가 이미 이름에 대한 기본 체계를 가지고 있기에 이를 잘 조합하여 이름을 짓자

easy to Agree: 수긍하기 쉽게 이름 짓는 법

수등할 수 있는 이름이란 누가 보더라도 그렇게 짓는 것이 더 낫다고 동의하는 이름이다. 이름 그 자체의 논리적 정합성이 있느냐 없느냐가 아니라 그 상황에서 그런 이름을 쓰는 것이 마땅하다고 생각할 수 있어야 하는 것이다.

easy to Remember: 기억하기 쉽게 이름 짓는 법

일상적이고 평법하고 무난한 점심은 뇌가 기억하지 않는다. 스스로 에너지를 효율적으로 사용하려는 뇌의 본능 때문이다. 반대로 얘기하면 비범하고 색다르고 인상적인 점심은 뇌가 스스로 기억해난다는 말이다. 뇌는 감각적인 것을 좋아한다.

시청각적으로 잘 지은 이름은 보통 연상어를 떠올려서 기억할 수 있도록 돕는다. (SSG의 쓱, SBS뉴스의 스브스 등)

easy to Type: 입력하기 쉽게 이름 짓는 법

자주 사용되거나 중요한 이름이라면 입력하기 쉬운지, 오타를 낼 가능성이 적은지, 다른 사람에게 말로 전달하기 쉬운지 검토해 보는 것이 좋다.

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

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

이름을 잘 지으면 주석을 대폭 줄일 수 있다. 이름이 주석이 할 일을 대신하기 때문이다.

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

주석이 필요한 때도 많다

개발자마다 영어 실력에 차이가 있어서 누구에게 쉬운 단어라도 누구에게는 처음보는 단어일 수도 있다. 어순을 잘못 이해하면 엉뚱하게 생각하기도 한다. 따라서 주석이 필요해질 수 있는데, 이 경우를 제외하고 생각하더라도 개발과정에선 주석이 필요할 때가 많다.

주석은 결국 코드의 정확성을 높이고 버그를 줄이는 계기가 되기에 꼭 함수나 변수이름으로 설명하기 어렵다면 주석을 달자 (물론 설계의 복잡성이 문제가 될 수 있다.)

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

코드는 의미를, 주석은 의도를

글은 의미를 전달하는 수단이다. 코드도 마찬가지다. 코드로 표현하지 못한 어떤 의도들은 주석으로 쓸 수밖에 없는데, 개발자가 어떤 의도를 전달하는 이유는 다른 개발자를 위한 것이다. 다른 개발자란, 미래의 본인도 포함한다.

주석의 반복

주석도 코드와 마찬가지로 반복적인 성격을 가지면 주석으로의 역할이 줄어들 수 있다. 위에서 부터 아래로 코드를 읽어나갈 때 같은 주석이 반복된다면 궁금증이 들 수 있다. 하지만 예제를 검색해보면서 이해하는 사람이 있다고 한다면 반복되는 주석은 반드시 지워야만 하는 것은 아니다.

주석의 발췌와 요약

발췌는 중요한 것을 뽑아내는 것이다. 중요한 것을 뽑으려면 덜 중요한 것을 빼야 한다. 한 문단에 같은 내용에 모두 주석을 달아 내용을 설명하기 보다 코드와 주석을 묶어 같은 내용을 한 묶음으로 설명하는 방식이 좋다. 또한 코드에 며시된 조건들은 주석에 넣기 보다 의도를 설명하는 주석을 달아야 한다.

주석도 코드다

주석의 유명한 말은 지속적인 유지보수가 되지 않는 주석은 쓰지 말라는 것이다. 주석은 코드와 마찬가지로 지속적으로 업데이트가 되어야 하는데, 의도나 이유를 설명하는 주석이 코드의 변경을 따라가지 못하면 다른 개발자는 너무 쉽게 오해한다. 코드는 디버깅이 가능하지만 주석은 그렇지 않다.

이러한 악순환에서 벗어나기 위한 가장 좋은 방법은 주석도 코드라고 생각하는 것이다. 코드 리뷰를 하며 주석도 같이 리뷰를 하고 불필요한 주석은 없애고 꼭 필요한 주석은 반드시 코드처럼 다뤄야 한다.

느낀점

다른 책에서 다루는 코드 작성법을 넘어 핵심적인 내용들을 잘 요약해둔 것 같다. 이런 내용을 읽고 실제 코드를 쓸 때 어느정도 반영이 되어서 들어가는 부분도 재밌다고 생각이 되지만, 결국 가장 좋은 것은 남의 코드를 많이 보고 내가 코드를 많이 작성해보는 것이라고 생각된다.

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

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

친절한 404, 불친절한 404

실제 화면에 보여지는 영역은 대부분 디자이너나 기획자가 만들어낸 영역이지만 개발자가 보여줄 수 있는 영역도 존재한다. 웹에서는 404, 소프트웨어에선 크래쉬가 발생했을 때 띄우는 페이지다.

이 페이지의 성격은 실제 개발되는 소프트웨어마다 천차만별로 구글의 경우엔 그냥 ‘찾을 수 없다’라고 뜨는 반면 위키피디아의 경우 다른 대안 링크나 이유를 명확하게 알려주는 페이지를 보여준다.

404가 죄송할 일인가?

에러페이지에서 사과를 해야하는 경우는 명확하다. 사용자가 해당 동작을 시도했지만 해당 동작 자체가 깨져서 제공할 수 없는 경우다. 이것을 ‘깨진 링크’, ‘죽은 링크’, ‘나쁜 링크’라고 한다.

깨진 링크는 개발자의 책임이다

실제로 내가 운영중인 블로그에도 깨진 링크가 10개 넘게 존재한다. 이는 블로그를 io로 다루면서 업데이트 되는 문서들의 링크가 깨져서 발생한 문제다. 저자의 말대로 따른 프로그램을 사용하거나 콘솔을 사용해 죄송할 일을 줄이자.

개발자용 에러 메시지와 사용자용 에러 메시지를 분리하자

에러 메시지에도 성격이 있다. 개발자가 사용하는 개발자용 에러 메시지와 사용자가 사용하는 사용자용 에러 메시지가 있다. 개발자용 에러 메시지는 디버깅을 위한 정보를 담고 있어서 사용자에게는 보여주면 안된다.

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

사용자 에러에 대처하는 메시지

사용자가 개발자의 의도대로 프로그램을 사용해야 하는데, 실제로는 그렇지 않은 경우가 많다. 따라서 의도하지 않은 동작에 대한 에러 메시지는 오류의 내용과 원인 그리고 해결 방법을 제시해야 한다.

에러 메시지를 보여주는 순서

만약 에러 메시지가 복잡하다면? 실제 내부적으로도 복잡한 상황에서 발생한 오류라면 이를 사용자에게 어느정도 까지 공개해야 할까?

먼저 복잡한 내용일수록 뒤로 숨기는 것이 더 바람직하다. 우선 에러 해결 방법을 먼저 제시하고 매끄럽지 않은 에러 원인과 내용은 다듬는다. 만약 사용자 메시지라면 이해하지 못할 수 있는 말들은 쉬운 말로 변경해서 보여준다.

오락가락 메시지와 버튼 메시지

이는 가끔 보이는 메시지와 버튼 메시지가 일치하지 않을 때 오는 불편함이다. 문서를 저장하거나 나가야 할 때 저장과 나가기가 아닌 예, 아니오로 되어 있는 경우나 예매해질 수 있는 모든 상황을 말한다.

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

버튼의 순서

버튼의 순서가 문제가 되는 이유는 확인, 취소와 같은 버튼들이 순서가 뒤죽박죽이라는 것이다. 윈도우에서는 확인이 먼저 나오고 그다음에 취소가 나온다. 대부분 확인이 오른쪽에 있는 이유는 행동의 연속성 때문이다.

우리는 글을 쓸 때 왼쪽에서 오른쪽으로 방향도 마찬가지다. 하지만 이는 국가나 문화의 차이가 있기에 국제 표준을 정하기 불가능하다. 따라서 현재 OS에 맞는 일관성을 가져가는 것이 가장 바람직하다. 필요하다면 시각적 효과를 강조하여 개발자의 의도대로 유도할 수 있다.

사용자의 반복 에러를 막는 법

사용자가 에러 메시지를 잘 이해해서 바로 에러 상황에서 벗어나면 좋겠지만 같은 에러를 몇 번이고 반복할 때가 종종 있다. 예를 들어 가장 많이 발생하는 비밀번호 틀림의 경우다. 이런 상황에서 같은 오류를 막기 위해 횟수로 제한하거나 자동 입력 방지 문자를 사용하는 방법이 있다.

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

서비스를 이해하면 에러를 예방할 수 있다

모든 개발자는 사용자가 에러 없이 프로그램을 사용하게 만들고 싶어 한다. 하지만 에러가 한 번도 발생하지 않게 프로그램을 온전히 개발할 수 있는 개발자는 없다. 사용자마다 사용법도 제각각이고, 아무리 메뉴얼이나 도움말을 적어도 무시하고 마음대로 사용하기 일쑤다.

에러를 줄이기 위해선 결국 개발자도 사용자의 사용 방식을 이해해야 한다.

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

사용자를 이해하는 것은 개발자로써 코드만 치면 되는거 아니야? 와 같은 생각으로 이어질 수 있지만, 현대의 개발은 유저와 소통하고 같이 개발해 나가며 질 좋은 소프트웨어를 만드는 것을 목표로 한다. 정말 작게 본다면 신용카드 번호를 적는 부분도 16자리를 한번에 적기보다 4자리씩 끊어서 적는 것이 사용자에게 더 편리하다.

비슷한 예로 이메일의 드롭박스, Caps Lock의 경고, 비밀번호 확인 등이 있다.

닭이 먼저? 알이 먼저?

개발자가 사용자를 불완전한 존재로 인식하는 순간 모든 사용자의 행동에 경고로 대응한다. 그러면 시스템도 불완전해진다. 사용자의 행동 하나하나가 불완전하므로 사용자의 모든 행동을 검증해야 한다. 사용자를 성인이 아니라 미숙아로 취급하는 것과 다름없다.

느낀점

이번 챕터는 에러 메시지와 관련한 챕터라 과연 게임에서는 어떤 경우가 있을까? 라는 생각을 주로 하며 읽었다. 엔진레벨에서는 크래쉬가 났을 때 사용자 메시지라기 보다 개발자용 메시지를 띄워주는 경우가 많은데, 아마 툴 사용자가 대부분 개발자이기 때문에 사유를 좀 더 개발자가 보기 쉽게 노출해주는 것 같다.

그럼 게임에서는 마찬가지로 대부분 예외라기 보다 예기치 못한 동작에 발생하는 크래쉬가 가장 많을 것이다. 해당 메시지는 대부분 개발사로 로그를 보내고 미안하다는 말과 재시작하는 통보가 가장 많을 것 같다.

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

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

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

어떤 일이든 하고 나서 그 일의 내용을 상사나 고객에게 글로 보고해야 할 때가 있다. 이때 체인지 로그를 작성하는데 너무 적거나 너무 많아도 좋지 않다. 읽기 좋게 적절한 양으로 써야 상사도 고객도 만족한다.

체인지 로그를 적절한 양으로 작성하기 위해서는 일단은 체인지 로그를 최대한 많이 써야 한다. 그다음에는 일정한 기준으로 선정하고 비슷한 것끼리 분류한 뒤 문장을 요약하는 기술이 필요하다.

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

1단계: 선정하기

체인지 로그의 양을 줄이려면 체인지 로그 중에서 쓸 것과 없앨 것을 구분하는 기준이 필요하다. 이때 개발자는 보통 자기가 오랜 시간을 들여 노력한 것을 쓰고, 그렇지 않은 것은 빼는 경향이 있다. 하지만 이런 기준으로 체인지 로그를 선정해서는 안 된다. 체인지 로그를 보는 사람의 입장은 다 다를 수 있기 때문이다.

실제로 따로 회사에서 표를 만들어 우선순위를 분류하거나 상황에 맞게 선정하는 방법을 사용하기도 한다.

2단계: 분류하기

공개할 체인지 로그를 선정했으면 비슷한 체인지 로그끼리 묶어야 한다. 이 때 두 가지 방법이 있다. 첫 번째 방법은 개발 관점에서 비슷한 작업으로 묶는 방법으로, 독자가 개발자인 경우 유용하다. 두 번째 방법은 독자가 일반 사용자인 경우에 유용하다.

두 방법의 차이는 개발 관점에서는 기능별로 묶는 것이고, 사용자 관점에서는 사용자가 느낄 수 있는 변화를 묶는 것이다.

3단계: 요약하기

체인지 로그를 분류했으면 문장 단위로 요약할 차례다. 여러 가지 요약 방법중에서 서술식 문장을 개조식 문장으로 바꾸는 방법을 쓰면 내용이 자연스럽게 축약되고 의미는 더 분명해진다. 개조식 문장을 만드려면 불필요한 부사나 형용사, 조사나 어미를 없애고, 정확하고 적절한 단어로 대체하면 된다.

4단계: 종합하기

체인지 로그는 결국 이전과 비교해서 핵심적으로 뭐가 달라졌는지 명확하게 보여줘야 한다. 릴리스 내용 전체를 종합해서 한 문장으로 만들고 그것을 체인지 로그 첫 줄에 적어야 한다. 전체를 종합하는 방법은 분석과 반대디.

종합이 분석과 반대라는 말은 “토끼는 동물이다”처럼 개념화하지 않고 “토끼는 귀가 밝다”처럼 특성으로 서술하거나 “토끼는 잘 도망간다”처럼 결과로 서술하거나 “토끼는 귀가 밝아서 잘 도망간다”처럼 특성과 결과를 합쳐서 서술하는 것이다.

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

개발자 관점과 고객 관점

체인지 로그는 개발자가 변경한 내용을 적은 것이다. 하지만 체인지 로그를 보는 독자는 뭔가 새로운 것, 바뀐 것,그래서 자기에게 좋거나 유리하거나 어떤 행동을 해야할지 명확한 정보를 원한다. 물론 체인지 로그가 개발자끼리 공유된다면 한일만 적어도 상관없다.

만약 체인지 로그가 고객에게 공개 예정이라면 해당 체인지 로그는 고객 관점으로 작성되어야 한다. 다음과 같은 체인지 로그를 보자.

댓글에서 애니메이션 스터커 때문에 화면이 멈추는 문제를 해결했습니다.

이것을 고객관점에서 살펴보자. 댓글에서 애니메이션 스터커 때문에 화면이 멈추는 것은 고객의 불편이 아니다. 고객은 화면이 멈춰서 애니메이션 스티커를 포함한 댓글을 쓸 수 없다는 것이다.

• 개발자의 문제: 화면이 멈춘 것
• 고객의 문제: 애니메이션 스터커를 댓글에 사용할 수 없는 것

개발자가 문제를 해결했다면 당연히 고객의 문제도 해결된다.

이를 고객의 문제 해결로 변경하면 다음과 같다.

이제 애니메이션 스티커를 정상적으로 댓글에 사용할 수 있습니다. 댓글에서 애니메이션 스티커 때문에 멈추는 문제를 해결했습니다.

또한, 체인지 로그를 꼭 하나의 관점으로 쓸 필요는 없다. 내용에 따라 관점을 적절히 선택하는 것도 중요하다. 소소한 것이라면 따로 기타로 묶어라. (예를 들어 첫 문장은 사용자 관점의 문제 해결, 두 번째 문장부터는 개발자 관점의 문제 해결)

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

체인지 로그 자체가 원래 개발의 결과니까 한 일을 적는 것은 당연하다. 하지만 아직도 잡아야 할 버그가 남아 있거나 연구 또는 개선 사항이 넘친다. 고객 입장에서도 이전에 해결된 문제가 다시 발생하지 않는지, 미래에 또 다른 문제가 발생하지 않을지 궁금할 것이다.

다소 귀찮지만, 이후 개발 예정인 항목에 대해서 어느정도 공개하는 것이 좋다.

Semantic Versioning (유의적 버전)

이는 유명한 버전 관리 방법으로, 버전을 통해 어떤 변화가 있었는지 알 수 있게 한다. 버전은 다음과 같이 구성된다.

• Major: 기존 버전과 호환되지 않는 변경 사항
• Minor: 기존 버전과 호환되는 새로운 기능 추가
• Patch: 기존 버전과 호환되는 버그 수정

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

문제와 문제점을 구별하자

체인지 로그는 간단하게 작성할 때가 많지만 만약 소프트웨어를 파는 기업SI라면 문서를 정식으로 만들어서 고객에게 제공해야 한다. 이때 릴리스 문서는 단순히 정보를 제공하는 것을 넘어서 고객에게 제공하는 문제 해결 보고서라고 할 수 있다.

버그를 잡거나 새로운 기능을 추가하거나 성능을 개선하는 것은 모두 어떤 문제를 해결하기 위해서다. 이때 문제는 목표와 현상 차이다. 목표는 있어야할 모습, 바람직한 상태, 기대되는 결과다. 현상은 현재의 모습, 예상되는 상태, 예기치 못한 결과다.

문제를 해결한다는 것은 목표에 다다르지 못하는 문제를 해결함으로써 현상을 목표에 일치시키는 것이다. 이러한 문제에는 발생형, 탐색형, 설정형의 세 가지 종류가 있다.

발생형 문제는 우리 눈앞에 발생해 당장 걱정하고 해결하기 위해 고민하는 문제다. 어떤 기준을 일탈하거나 미달해서 생기므로 원상 복구가 필요하다. 프로그램 에러가 대부분 발생형 문제다.

탐색형 무넺는 현재 상황을 개선하거나 효율을 높이는 문제다. 이 문제는 눈에 잘 보이지 않으므로 그냥 놓아두면 뒤에 큰 손실이 따르거나 해결할 수 없는 문제로 커진다. 프로그램 개선이나 시스템 효율화가 대부분 탐색형 문제다.

설정형 문제는 미래 상황에 대응하는 문제다. 앞으로 어떻게 할 것인가 하는 문제다. 지금까지 해오던 것과 관계없이 새로운 과제나 목표를 설정함으로써 일어나는 문제다. 새로운 기능 추가나 새로운 시스템 구축이 대부분 설정형 문제다.

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

하나의 문제에 문제점은 여러 가지이고, 여러 가지 문제점을 모두 해결하기에는 예산과 인력이 늘 부족하므로 특정 문제점을 선택할 수 밖에 없다. 그러므로 어떤 문제점을 선택하느냐에 따라 문제 해결 방법은 완전히 달라진다.

릴리스 문서는 결국 개발자가 문제점 하나를 선택해서 해결한 결과다. 따라서 여러 문제점 중에 어떤 문제점을 선택했는지를 독자에게 정확히 알려줘야 한다.

• 문제: 사용자가 급증하면 서버가 정지
• 문제점: 잘못된 시스템 설정, 프로그램 비 최적화, 잘못된 DB 설계 (사용자 증가는 문제점이 아니다.)
• 해결책: 시스템 설정 변경
• 후속 계획: 프로그램 최적화, DB 재설계

위 내용으로 릴리스 문서를 작성하면 다음과 같다.

000 서비스에 사용자가 급증하면 00 서버가 정지하는 문제는 시스템 재설정으로 해결했습니다. 추후 프로그램 최적화와 DB 재설계도 검토하겠습니다.

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

릴리스 노트의 핵심은 문제 해결의 과정과 결과를 고객에게 알려주는 것이다. 여기에 덧붙여 노트도 보고서의 일종인 만큼 형식도 갖춰야 한다.

• 문서 정보: 제품명, 릴리스 이름, 릴리스 버전, 릴리스 날짜 등
• 개요: 릴리스 노트의 주요 내용을 종합한 글
• 새로운 기능: 이번 릴리스에서 새롭게 추가한 기능
• 개선 사항: 버그 내용과 수정 사항
• 영향과 주의사항: 릴리스로 인한 영향과 개발자의 주의사항
• 연락처: 문의나 의견 접수를 위한 담당자 이름과 연락처 정보
• 면책: 변경 사항이나 릴리스 문서로 인한 법적 문제 발생 시 책임의 한계에 관한 내용

이런 문서인 만큼 법적인 문제를 피하기 위해 면책 조항을 작성하는 것이 좋다. (너무 강압적이지 않게)

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

장애 보고서의 특징

고객사 서비스 운영을 대행하는 개발자가 가장 싫어하는 것이 장애보고서 작성이다. 장애 보고서의 특징들을 알아보자.

• 장애 보고서는 개발자가 원할 때 쓸 수 없다.
  • 장애가 발생하기 전에 쓸 수도 없고, 예상도 불가능하다. 즉, 해당 장애를 인지하고 해결 직후나 다음날까지가 쓰는 시간이다.
• 장애의 1차 원인은 대부분 다른 원인의 결과다.
  • 장애의 원인을 알아내려면 원인의 원인을 계속 찾아 나가야 한다. 더는 원인을 찾을 수 없을 때 그 원인이 최초 원인이다.
• 장애 보고서를 받는 윗사람은 대부분 개발자가 아니다.
  • 특히 임원들은 장애를 곧 비즈니스에 주는 영향으로 본다.
• 장애를 해결했다고 해서 100% 해결한 것은 아니다.
  • 장애란 것이 원래 예상하지 못한 데서 발생한 것이니, 지금 어떤 처치를 했다고 해서 다시는 재발하지 않는다고 단정할 수 없다.

요약하자면 장애 보고서를 작성할 때는 다음과 같은 글쓰기 기법이 필요하다.

1. 질문에 대답하는 신속한 글쓰기
2. 원인과 이유를 찾는 분석적 글쓰기
3. 상사를 고려하는 비즈니스 관점의 글쓰기
4. 원하는 것을 얻는 정치적 글쓰기

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

글을 빨리 쓰는 방법 중에 대화를 글로 옮기는 방법이 있다. 가까운 동료와 대화할 때 우리는 깊이 생각하느라 한참을 뜸 들이거나 할 말을 정하지 못해서 말을 안하는 경우는 없다. 일단 무슨 말이든 내뱉고 나서 생각을 정리하고, 질문 받으면 답하면서 다음 생각으로 이어진다. 이 방법을 글쓰기에 그대로 적용하면 신속하게 글을 쓸 수 있다.

우선 장애를 아주 단순하게 주어, 목적어, 서술어로만 쓰자

“사용자가(주어) 결제를(목적어) 할 수 없다.(서술어).”

이후 이 문장에 동료가 답한다고 생각하고 아는 대로 말로 대답하듯이 작성한다.

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

문제 해결 기법 중에 5Whys가 있다. 이것은 어떤 문제의 원인을 찾을 때 피상적인 원인이 아니라 근본적인 원인을 찾는 기법이다. 문제의 원인이 되는 인과 관계를 탐색할 때 다섯 번 반복해서 원인이 무엇인지 질문하는 방식이다.

반복해서 “왜?”라고 질문함으로써 근본 원인을 찾는 것이다. 여기서 Why는 두 가지 뜻으로 이해해야 한다. 첫째는 사물이나 현상, 동작이 문제를 초래하는 원인, 둘째는 사람이 문제를 초래한 이유다. 원인은 어떤 일이나 사건이다. 이유는 사람이 어떤 일을 하거나 하지 않은 까닭이나 동기다. 즉, why는 어떤 일 또는 사람이다.

IT업계에서 장애는 대부분 재발한다. 재발하는 원인은 시스템 자원이 늘 부족하기 때문이기도 하지만, 대부분 사람의 문제다. 즉 개발자 사이의 커뮤니케이션 오류가 바로 핵심이다.

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

“가진 것이 망치뿐이면 모든 것이 못으로 보인다”라는 말처럼 각자 자기 위치와 입장에서 최선을 다하는 것뿐이다. 즉, 각자의 입장을 이해하고 이 사실을 인정해라. 그래야 윗사람에게 보고할 때 그들과 같은 비즈니스 관점에서 할 수 있다.

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

장애는 보통 예상하지 못한 곳에서 발생한다. 그리고 장애를 해결했다고 다시 발생하지 않을 보장도 없을 뿐더러 재발할 때마다의 미묘한 차이가 있다. 이런 경우엔 설명하기 너무 어렵고 애매할 때가 많다.

따라서 어느정도 정치적인 글쓰기 기법이 필요하지만, 회사의 경우엔 이를 명확하게 전달하는 것이 더 중요하다.

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

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

범주, 용도, 특징

개발 가이드의 첫 문단은 서비스 개념을 설명하는 자리이기에 제대로 개념을 잡지 못하면 이후에 나오는 내용을 제대로 이해할 수 없다. 이런 서비스 개념을 설명할 때는 범주, 용도, 특징 순으로 쓰는 것이 좋다. 독자가 잘 아는 범주를 먼저 말하면 독자는 자연스럽게 머릿속으로 해당 범주를 떠올린다.

그다음에 범주의 용도를 말하면 독자는 자연스럽게 서비스의 용도와 같음을 알아차린다. 마지막으로 범주 내의 유사 서비스와 차별화하는 특징을 말하면 독자는 서비스의 개념을 정확히 이해한다.

예시로 네이버 클로바 개발 가이드 문서의 첫 문단이다.

• 범주: Clova는 NAVER가 개발 및 서비스하고 있는 인공지능(AI) 플랫폼입니다.
• 용도: Clova는 사용자의 음성이나 이미지를 인식하고 이를 분석하여 사용자가 원하는 정보나 서비스를 제공합니다.
• 특징: 3rd Party 개발자는 Clova가 가진 기술을 활용하여 인공 지능 서비스를 제공하는 기기 또는 가전제품을 만들거나 보유하고 있는 콘텐츠나 서비스를 Clova를 통해 사용자에게 제공할 수 있습니다.

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

개발자는 독자가 이미 가진 범주를 사용함으로써 서비스의 개념을 간단하고 정확히 설명할 수 있다. 여기서 주의할 점은 동물이나 사물의 범주를 가진 단일 용어를 사용하는 것과 달리, 산업이나 서비스의 범주는 유사한 용어가 많다는 것이다.

개발자가 만약 지나치게 트렌드에 앞선 범주를 선택하거나 구체적인 단어를 선택하는 경우 독자는 이해하기 어려워진다. 가장 좋은 방법은 여러 경쟁사가 사용하는 보편적인 서비스 범주를 따라 하는 것이다.

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

첫 문단의 첫 문장이 범주로 적혀있다면 두 번째 문장은 독자 관점의 용도를 적는다. 용도는 독자가 이 서비스를 이용하는 이유다. 즉, 해당 서비스의 핵심 기능을 말한다.

범주의 핵심 기능을 용도로 설명함으로써 독자의 머릿속에 서비스의 정체성을 명확하게 하는 것이다. (비유하거나)

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

범주와 용도에는 보편적인 내용을 적는다. 하지만 특징은 차별화하는 내용을 적어야 한다. 개발자에게 차별화는 서비스의 장점과 강점이다. 장점은 자기 기준에서 잘하는 것이고, 강점은 경쟁 서비스와 비교했을 때 뛰어난 것이다.

장점은 자기 기준인 반면 강점은 시장 기준이다.

정확히 이해하도록 그림과 글로 묘사하자

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

묘사는 어떤 대상이나 사물, 현상을 언어로 서술하거나 그림을 그려서 표현하는 것이다.

개발문서는 꽤 복잡한 글이다. 이를 잘 이해하기 위해선 묘사가 필요하다. 즉, 묘사가 필요없이 처음부터 그림을 제공하자.

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

그림에서는 인공지능 서비스라고 다루고 글에선 클라이언트라고 다룬다면 독자는 혼란스러워한다. 그림과 글의 내용을 일치시키자. 같은 내용을 다른 용어로 표현하지 말고 같은 용어로 표현하자.

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

길을 잃은 사람에게 길을 알려준다고 할 때 주관적 묘사와 객관적 묘사는 다음과 같이 차이가 난다.

• 주관적 묘사: “저기 앞에 큰 사거리에서 오른쪽으로 돌아서 5분쯤 가면 기차역이 보여요”
• 객관적 묘사: “두 번째 사거리에서 10시 방향으로 돌아서 300미터 가면 우측에 기차역이 있어요”

개발 과정에서 나오는 문서를 보면 주관적 묘사를 많이 하다가 객관적 묘사가 크게 늘고 마지막에는 주관적 묘사가 다시 늘어나는 경향이 있다.

개발자와 기획자 사이에서 가장 많이 발생하는 문제로 기획자의 주관적 묘사를 개발자는 객관적 묘사로 보며 요구사항 정의서를 만들기 시작한다.

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

의견을 쓰려면 근거를 대자

논증은 옳고 그름을 이유나 근거를 들어서 밝히는 것이다. 논술과 비슷한데, 논술은 논증의 기법으로 기술하는 것이다. 논술의 핵심은 논증인 셈이다. 논증은 객관적이고 논리적인 방식으로 어떤 사실을 증명해서 상대를 설득하는 일이다.

명확한 근거를 제시하는 문서를 작성해라.

거칠게도 공손하게도 쓰지 말자

개발자가 개발 가이드 문서를 쓰면 은근히 대장 노릇을 할 때가 있다. 자기도 모르게 권력과 힘을 드러내거나 자랑한다. 가장 대표적인 것인 ‘~할 수 있지만 ~하기 어렵다.’같은 문장이다.

개발 문서에서 공손한 표현은 좋지 않다. 공손하게 말하는 순간 오해할 소지가 있다. 개발자가 자주 쓰는 공손한 표현에는 다음과 같은 것들이 있다.

• ~해야 합니다만 반드시 해야 하는 것은 아닙니다.
• ~하면 좋습니다. 다만 ~한 경우에는 안 해도 무방합니다.
• ~하지 말아야 합니다. ~한 경우에는 어쩔 수 없으니 넘어가도 됩니다.
• ~하지 마십시오. 물론 큰 문제는 없습니다.
• ~할 것을 추천합니다. 혹시 더 좋은 방법이 있을 수도 있습니다.

이런 표현은 다음과 같이 바꾸자.

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

세상에는 어떤 일이든 100% 확신할 수 없다. 따라서 독자에게 어떠한 여지도 줘서는 안 된다.

주장과 이유의 거리를 좁혀서 쓰자

주장을 했으면 이유를 바로 이어서 말해야 한다. 앞에서 이유를 말했다고 해서 지금 주장만 하고 이유를 말하지 않으면 안 된다. 특히 개발문서는 잡지와 같아서 처음부터 순서대로 읽지 않는다. 그때그때 필요한 부분을 찾아보기 때문에 주장을 말했으면 중복되더라도 이유를 함께 말하거나 이유를 찾을 수 있는 곳을 알려줘야 한다.

문제와 답의 거리를 좁혀서 쓰자

논증은 문제 해결과 비슷하다. 논증 자체가 어떤 문제에 대한 특정한 의견이기 때문이다. 개발에서는 문제 하나를 해결하는 방법이 하나밖에 없는 경우는 드물다. 해결 방법이 여러 가지여서 그중 최선을 선택하는 것이 개발 과정이다.

쉽게 문제와 답에 대한 거리를 줄이고 가는 방법에 대한 내용을 뒤에서 후술한다.

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

개발과 서사

서사는 사실을 있는 그대로 순서대로 적는 것을 말한다. 누가 어떤 행동을 했고, 그 행동으로 어떤 일이 일어났는지 그대로 쓰는 것이다. 소설은 대부분 서사 방식으로 쓰여 있다.

개발에서도 서사를 많이 쓴다. 소설과 다른 점은 어떤 일을 하라고 지시한다는 것이다.

많이 사용하는 방법으로 스크린숏안에 번호를 매개 서사를 통해 단계별로 설명하는 방법이 있다.

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

서사가 순서대로 글을 쓰는 것이기는 하지만 단순한 사건이나 상황을 시간순으로 기술하는 것은 아니다. 그것보다는 의미 있는 사건을 시간에 따른 전개 과정으로 써야 한다. 그래야 서사다.

개발문서에서 서사는 결국 개발자와 독자 사이의 줄다리기 같은 것이다. 개발자는 의미 없는 것은 빼고 중요한 것을 넣기를 원한다. 독자도 의미 있는 것만 남고 무엇이 중요한지 구별해 주기를 원한다.

가장 좋은 방법은 기술의 범용성을 기준으로 하는 것이다. 현재 시대에 맞는 기술 범용성을 이해하고 범용적으로 작성하자. (결국 다른 문서를 참고하자)

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

개발 가이드나 사용법, 도움말 등의 문서에 서사가 많다. 독자가 프로그램을 에러 없이 사용하도록 하기 위해서다. 그런데 어떤 복잡한 것을 순서대로 말하려면 글이 너무 길어진다. 게다가 앞뒤 행동이 연결되는 것도 있지만, 크게 바뀌는 경우도 있다.

만약 25개의 단계가 필요하다면 이를 계속 따라고 하고 있는 독자는 지금 뭘위해서 뭘 하는것인지 전혀 인지하지 못한다. 따라서 단계 개념을 사용한다. 1~5번은 버그 재현(예시)이라는 단계를 둬서 자신이 어디에 있는지 알 수 있게 한다.

각 단계는 반드시 목표가 있어야 한다. 그래야 단계를 통과할 수 있다. 이런 부류의 문서는 대부분 처음에는 쉽고 뒤로 갈수록 어려워진다. 그래서 단계에서 쉬운 목표를 달성하면 조금씩 어려운 단계의 목표를 달성하게 만들어야 한다.

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

SI부분은 최대한 요약해서 작성, 나중에 필요하면 다시 읽어보기

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

개발자와 제안 PM의 차이

개발자라고 코드만 작성하지 않는다. 업계에 따라 개발자도 제안서를 많이 작성해야 한다.

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

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

개발자가 기술 블로그를 잘 못 쓰는 이유

개발자가 기술 블로그를 잘 못 쓰는 이유 중 하나는 블로그에 글을 쓰는 방법이 학생이었을 때 배운 글쓰기 방법과 다르기 때문이다. 학생이었을 때 배운 글쓰기 방법은 주로 논설문이나 설명문을 쓰는 방법이었다. 논설문이나 설명문은 목적이 분명해야 해서 다음 질문에 먼저 답할 수 있을 때 비로소 글쓰기를 시작할 수 있다.

• 이 글을 왜 쓰는가?
• 이 글을 읽는 독자는 누구인가?
• 이 글을 읽는 독자에게 무엇을 말하려고 하는가?
• 이 글이 주장하는 바가 무엇인가?
• 이 글이 주장하는 바의 근거가 분명한가?

이런 질문에 대답해야 하니 글쓰기는 자연스럽게 문제해결 과정이 되었다. 글쓰기를 문제해결 과정으로 배운 것이다. 문제해결 과정의 핵심은 문제를 충분히 고민하여 해결 방안을 전략적으로 선택하는 것이다. 이를 글쓰기에 대입하면, 글을 쓰기 전에 계획을 세우는데, 이 계획 단계에 시간을 충분히 할애해야 한다.

무턱대고 글부터 쓰면 안 되고, 충분히 생각해서 주제를 정하고 주제 의식을 확립한 후 글을 쓸 때 자료나 아이디어를 구해야 한다. 그러고 나면 독자를 분석해서 글의 수준이나 방향을 정해야 한다.

기술 블로그를 읽는 독자의 수준은 일정하지 않다. 개발자 블로그를 보는 사람은 대부분 개발자이지만, 개발자의 폭과 깊이가 천차만별이다. 개발자의 블로그는 딱히 주장도 없다. 단지 개발자가 했던 선택과 몇몇 상황에서 더 좋은 방법을 제시할 수 있을 뿐이다. 독자에게 그렇게 하라고 주장해서 설득하고 싶은 마음을 가진 개발자는 전혀 없다.

저자가 추천하는 블로그에 글 쓴느 적합한 3가지 방법을 소개한다. 첫째 소재 우선 글쓰기, 둘째 자기 수준 글쓰기, 셋째 재미있는 글쓰기다.

첫째, 주제 의식을 버리고 소재 의식으로 쓰자

소재 우선 글쓰기는 주제 의식이 아니라 소재 의식을 갖고 쓰는 것이다. 주제 의식이 민족이나 권선징악, 자존감이나 자본주의와 같은 추상적 가치를 기반으로 한다면 소재 의식은 특정한 대상이나 상황에 대한 자기만의 관점이나 생각, 해결 방안을 뜻한다.

• ex) 소재 의식: 데이터베이스의 자동증가 값을 기본키로 사용할 수 없을 때는?

이러한 점에서 기술 블로그는 일상을 다룬 수필이나 에피소드와 비슷하다. 수필을 평가하는 평론가나 국어 선생님들이 수필의 주제를 찾는 것이지, 수필을 쓰는 사람은 그저 일어난 이야기를 할 뿐이다.

둘째, 독자 수준이 아니라 자기 수준으로 쓰자

글쓰기 전문가들은 다른 글을 쓸 때 초등학생도 이해할 수 있도록 쉽게 풀어서 쓰라고 한다. 하지만 직장에서 하는 일을 초등학생에게 풀어서 설명하기는 어렵다.

면접에서 정말 많이 나오는 질문인 초등학생, 중학생 수준이라고 생각하고 기술을 설명해달라는 질문이 있다. 이 질문에 대한 답변은 대부분이 비유를 하여 쉽게 설명한다.

개발자가 기술 블로그를 쓸 때는 독자를 생각해서 굳이 어려운 용어를 해석해 풀어쓰거나 쉬운 용어로 바꿀 필요가 없다. 원래 사용하는 용어로 표기하되, 필요하다면 그 용어를 설명하는 링크를 걸어두면 된다. 기술 블로그란 것은 결국 실력이 비슷한 독자를 위한 것이다. 독자에게 설명하는 것이 아니라 핵심만 쓰고 나머지는 독자가 공부할 수 있게 길만 터놓는 것이 현명한 방법이다.

그래야 개발자도 자기가 쓰려는 글의 본질에 집중할 수 있다.

셋째, 재미있는 글을 쓰자

논문이나 기술 메뉴얼, 사용 설명서를 쓸 때는 자신의 경험을 녹여내거나 글의 기교를 부릴 여지가 별로 없다. 이런 글은 군더더기 없이 깔끔하지만, 글 쓰는 재미나 읽는 재미가 별로 없다.

글쓰기 기교는 글을 아름답게 만들고 쉽게 읽히게 한다. 기교를 부리다 보면 글쓰기가 재미있고 글도 재미있어진다. 글에 재미가 있으면 독자가 활발히 반응하고 독자의 반응이 활발하면 블로거는 글을 계속 쓸 동력을 얻는다. 글쓰기 기교는 이렇게 선순환을 만든다.

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

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

개발자가 기술 블로그에 쓰는 종류는 매우 다양하다. 직접 개발한 과정, 튜토리얼, 개발 가이드, 에러나 버그를 해결하는 방법, 세미나 후기나 책 리뷰, 스스로 깨달은 교훈, 각종 레퍼런스, 개발 상식 등 수도 없이 많다. 하지만 이런 글은 모두 4가지로 분류할 수 있다.

구분	내용	종류
저	직접 경험하고 실험한 내용이나 결과	개발기, 도입기, 적용기
술	어떤 것을 분석하여 의미를 풀이하고 해석한 것	기술 소개, 용어 분석, 에러 해결 방법 등
편	산만하고 복잡한 자료를 편집해 질서를 부여한 것	프로그램 설치/설정 방법, 튜토리얼, 세미나 후기, 책 리뷰
집	여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것	명령어 모음, 팁, 00가지 규칙

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

저는 직접 경험한 것을 쓴 것이다. 개발 과정과 결과를 쓴 개발기가 여기에 해당한다.

• 맵 절차적 생성기를 활용한 게임 개발기
• 유니티 게임 고도엔진으로 포팅하기

개발 과정과 결과를 다룬 개발기를 쓸 때는 무엇보다 목차를 잘 구성해야 한다. 목차만 제대로 잡으면 다른 종류의 글보다 쓰기 쉽다. 다시 말하면, 많은 개발자가 개발기 목차를 구성하지 못해서 개발기를 잘 못 쓴다.

개발기 목차는 1차원 단방향이다. 1장 다음에는 2장이 이어지고, 2장 다음에는 3장이 순서대로 이어진다. 하지만 개발자의 경험은 2차원 양방향이다. A문제를 해결하려고 했지만, 다시 E문제가 생기고 F코드를 썼는데 G 버그가 생겨서 한참을 복기하다가 H 코드로 바꾸는 식으로 경험한다. 그래서 개발자 머릿속에는 자신의 경험이 길을 잃고 헤매다 겨우 목적지에 도착한 모습으로 남아 있다. 이렇게 복잡한 2차원 양방향 개발 경험을 1차원 단뱡향 목차로 바꾸어야 하니 어렵다.

2차원 양방향 경험을 1차원 단방향 목차로 바꾸는 핵심 방법은 최종적으로 성고한 루트와 실패한 루트를 구별하는 것이다. 내 생각에는 위에서 말한 결험들이 잘 버전관리가 되어 있고, 문서화가 되어있다면 더 좋을 것 같다.

위 내용대로 구별을 잘해서 목차를 구성했다면 보통 머리말부터 글을 쓰려할텐데 개발자가 가장 어려워하는 내용이 머리말이다. 본문을 잘 적고 이후에 작성하자.

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

술은 어떤 것을 분석해 의미를 풀이하고 해석한 것이다. 인문학에서 술은 경전을 해설한 글을 말한다. 개발에서 술은 새로운 기술을 자세하게 또는 비유해 설명한 것, 비슷한 용어를 비교해 풀이한 것, 에러 해결 방법 등이 여기에 해당한다. 예를 들면 다음과 같은 글이 술에 해당된다.

• C++11의 auto 키워드 사용법
• 유니티 ScriptableObject에 대한 이해

인문학에 경전이 있는 것처럼 개발에도 원전, 즉 원서나 원문, 프로토콜이나 레퍼런스가 있다. 그래서 술에 해당되는 기술 블로그를 쓸 때는 본래 내용을 바탕으로 자기 생각이나 분석, 해설을 덧붙이는 방식으로 쓰는 게 좋다.

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

편: 순서를 요약하여 쓰자

편은 산만하고 복잡한 자료를 편집해 질서를 부여한 것이다. 프로그램 설치나 설정 순서, 개발 방법, 튜토리얼, 컨퍼런스 후기 등이 해당된다.

편을 쓰는 방법은 저술보다 쉽다. 시간 순서로 하나씩 나열해 내용을 쓴 다음, 단계로 묶어서 요약하기만 하면 글이 완성되기 때문이다.

작성에 대한 팁은 일단 글을 순서대로 쭉 쓰고, 목차를 정한뒤 내용을 자세히 적으면 된다. 여기에 단계를 더해 질서 있게 보여준다.

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

집은 여러 살마의 견해나 흩어진 자료를 한데 모아 정리하는 것이다. 자료가 아니라 비슷한 여러 책을 한데 모아 출간한 것을 전집이라고 하는데, 이때 ‘집’은 단순히 여러 책을 모은 것이고, 지금 말하는 ‘집’은 자료를 모아 하나의 책으로 엮은 것이다.

집은 여러 자료를 하나로 묶기 때문에 이것저걱 아무렇게나 집어넣을 수가 없다. 따라서 요점만을 축약해서 모아야 하는데 이를 집요라고 한다.

• 좋은 코딩을 위한 13가지 규칙
• 유니티 사용 팁 모음

대부분 이런 글들이 조회수를 담당하며 이는 고수보다 초보자가 더 검색을 많이하기 때문이다. 개발을 다룬 저술은 쓰기 어렵지만 꾸준히 천천히 쓰며 익숙해지자