티스토리 뷰
◈소개
개발자는 정확하고 간결하고 가독성이 높은 글을 쓸 수 없는 것일까? 그렇지 않습니다. 수준의 차이는 있지만 조금만 공부하고 연습하면 개발자 누구나 정확하고 간결하고 가독성이 높은 글을 쓸 수 있습니다. 그런데 지난 수십 년 동안 개발 방법과 개발 도구는 엄청나게 발전했지만, 개발자의 글쓰기 실력은 그다지 나아지지 않았습니다. 구글이나 네이버 같은 대기업은 테크니컬 라이터가 따로 있어서 개발 가이드 같은 문서를 잘 쓰고 관리도 잘합니다. 하지만 보통 개발자는 글 한 줄 쓰기가 참 어렵습니다. 개발 가이드라도 만들어야 한다면 여간 괴로운 일이 아닙니다. 개발자가 글을 어려워하는 이유는 많지만, 그동안 개발자를 위한 글쓰기 교육이 없는 것, 관련된 자료서적이 없는 것도 이유가 됩니다. 큰 It기업에 개발자로 입사해도 일반적인 비즈니스 보고서 작성법만 배웁니다. 개발자가 현업에서 필요로 하는 글쓰기 방법은 배울 수 없습니다. 정작 개발자에게 필요한 변수 이름, 네이밍 컨벤션, 주석, 에러 메시지, 릴리스 노트, 장애 보고서, 개발 가이드, SI제안서, 기술 블로그 같은 것을 쓰는 법은 어디서도 배울 수 없습니다. 요즘은 개발자가 다른 사용자나 개발자, 잠재 고객과 소통하는 일이 잦아졌습니다. 깃허브 등을 통해 개발자가 만든 코드를 공개하고, 개발자 사이트를 통해 외부 개발자와 협력하는 일도 늘었습니다. 그러다 보니 개발하는 것만큼 글 쓸 일이 많아졌습니다. 이 책은 이러한 개발자의 글쓰기 능력을 종합적으로 향상하기 위한 책입니다. 그래서 제가 소개할 부분은 개발자가 알아야 할 글쓰기 기본과, 네이밍 컨벤션, 장애 보고서 쓰는 법, 개발자가 기술 블로그를 쉽게 쓰는 3가지 방법 등을 소개하고자 합니다.
◈문장과 단락을 구조화하는 법
예를 들어 "색상 RGB값을 각각 사용하기 때문에 입력 데이터는 3차원 벡터다."라는 문장을 인과 관계를 나누어 복문 두 문장으로 나누어 보면, "입력 데이터는 색상 RGB값을 각각 사용한다. 그래서 입력 데이터는 3차원 벡터다"로 표현됩니다. 이 문장을 쓰려면, 머릿속에서 본인이 잘 아는 내용, 즉 '입력 데이터는 3차원 벡터다'를 떠올리면 됩니다. 그리고 바로 씁니다. 그러면 "입력 데이터는 3차원 벡터다" 이제 입력 데이터가 3차원 벡터인 이유를 어떻게 설명할 것인지 결정하면 됩니다. 색상은 보통 RGB의 세 값을 사용하므로 그래픽 프로그램을 조금이라도 이해하는 사람이라면 당연히 3차원 벡터를 이해할 것입니다. 이런 사람들이 읽는 글이라면 "입력 데이터는 3차원 벡터다"라고만 써도 충분합니다. 굳이 추가 설명을 덧붙일 필요가 없습니다. 하지만 그래픽 프로그램에 익숙하지 않은 사람을 위해 '색상 RGB 값을 각각 사용하기 때문입니다.'라고 부가 설명을 추가할 수도 있습니다. 문장을 쉽게 쓰려면 이렇게 "입력 데이터는 3차원 벡터다. 색상 RGB값을 각가 사용하기 때문이다."로 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 됩니다. 개발자의 생각을 글로 표현하는 데는 크게 세 가지 방법이 있습니다. 첫째는 서술식입니다. 서술식은 바로 앞의 문장처럼 '~다'로 끝나는 완전한 문장으로 구성된 글을 말합니다. 무엇을 설명하거나 논증할 때 주로 사용하는 방식입니다. 소설이나 신문 기사처럼 개발 가이드 문서는 대부분 서술식으로 씁니다. 둘째는 개조식입니다. 개조식은 신문의 헤드라인을 쓰거나 어떤 사항을 나열할 때 사용합니다. 행사의 개요를 적을 때 일자, 장소, 참가자 등을 종결 어미, 대신 명사나 용언의 명사형으로 끝내는 것을 개조식이라 합니다. 셋째는 도식입니다. 도식은 사물의 구조나 관계, 상태를 그림이나 서식으로 보여주는 것입니다. 이때 가장 간단한 형태의 도식은 행과 열로 이뤄진 표입니다. 행렬에 글만 있으면 표라 하고, 막대 같은 그림이 있으면 도표라고 합니다. 단락을 구조화하는 방법은 문단과 문단 사이에 위계가 있어야 합니다. 비즈니스 문서에 위계가 없으면 비즈니스 문서가 아니라 소설이 됩니다. 이때 위계는 위치와 계층을 합한 말입니다. 위치는 2차원 평면의 좌표를 의미합니다. 급이 낮은 문장은 더 들여 쓰기 함으로 위치를 맞춥니다.
◈네이밍 컨벤션, 이유를 알고 쓰자
네이밍 컨벤션이란, 식별자를 만들 때 가독성이 좋도록 단어를 한눈에 보기 위해서 규정한 이름 짓는 규칙입니다. 아무리 작은 프로그램이나 간단한 애플리케이션이라도 수많은 이름을 지어야 합니다. 변수 이름부터 시작해서 함수, 클래스, 파일, 디렉터리, 데이터베이스 칼럼, 심지어 프로젝트 이름까지 정해야 합니다. 설문조사에서 개발자 대부분이 이름 짓기가 힘들다고 합니다. 개발자들이 이름 짓기를 어려워하는 이유는 무에서 유를 창조해야 한다는 생각 때문입니다. 하나, 이름 짓기는 무에서 유를 창조하는 것이 아닙니다. 기존 방식이나 이름을 차용해서 새로운 이름을 짓는 경우가 대부분입니다. 네이밍 컨벤션은 기본적으로 영어의 표기법을 준수합니다. 그래서 영어 표기법을 이해하면 네이밍 컨벤션도 이해할 수 있습니다. 예를 들어 대소문자를 구별하는 파스칼 표기법과 카멜 표기법은 영어의 대문자 표기원칙을 상속받은 것입니다. 고유명사는 문장 어느 위치에서 오든 첫 글자를 대문자로, 요일명, 휴일명, 달, 역사적 사건, 천체, 역사적 기간은 첫 글자를 모두 대문자로 씁니다. 표기 원칙을 잘 보면 몇 가지 특성이 있습니다. 첫째, 중요하거나 크거나 특정한 것을 가리키거나 제목에 해당하는 명사는 모두 첫 글자를 대문자로, 둘째, 그런 명사들이 이어질 때는 첫 글자를 모두 대문자로 씁니다. 셋째, 명사나 관사가 아닌 동사, 형용사 등은 소문자를 씁니다. 상수는 모두 대문자로, 패키지와 모듈은 소문자로 쓰는 것이 낫습니다. 제일 중요한 것은 가독성과 소통입니다. 근데 가독성이 높다고 소통이 더 잘 되는 것은 아닙니다. 소통이 잘 되려면 서로가 같은 컨벤션을 지켜야 한다는 점 명심하기 바랍니다.
◈ 장애 보고서의 특징 및 쓰는 법
고객사 서비스 운영을 대행하는 개발자가 가장 싫어하는 일은 장애 보고서 작성입니다. 하지만 장애 보고서를 쓸 사람은 개발자 말고는 없어서, 개발자가 장애도 고치고 보고도 해야 합니다. 장애 보고서란 것이 보통의 개발 문서와 크게 달라서 장애 보고서의 특성을 충분히 이해하고 쓰지 않으면 쓸모가 없습니다. 장애 보고서 특성을 하나씩 짚어보겠습니다. 첫째, 장애 보고서는 개발자가 원할 때 쓸 수 없습니다. 장애가 발생하기 전에 미리 쓸 수도 없고, 장애를 예상하고 쓸 수가 없어서 오직 장애가 발생해서 인지하는 순간부터 장애 해결 직후나 다음 날 오전까지 장애 보고서를 쓰는 시간입니다. 둘째, 장애의 1차 원인은 대부분 다른 원인의 결과입니다. 장애의 원인을 정확히 알아내려면 원인의 원인을 계속 찾아 나가야 합니다. 더는 원인의 원인을 찾을 수 없을 때 그 원인이 장애의 최초 원인입니다. 그런데 장애의 재발을 막으려면 원인만 해결해서는 안됩니다. 그 원인이 발생한 이유를 알아야 합니다. 이유는 사람에게 있습니다. 원인과 이유를 찾는 분석적 글쓰기가 필요합니다. 셋째, 장애를 해결했다고 해서 100% 해결한 것은 아닙니다. 장애란 것이 원래 예상하지 못한 데서 발생한 것이니, 지금 어떤 처치를 했다고 해서 다시는 재발하지 않는다고 확정할 수 없습니다. 그래서 윗사람에게 보고할 때는 확정적이고 신뢰할만한 결단을 정치적으로 내려야 합니다. 그래서 정치적 글쓰기가 필요합니다. 장애 보고서를 쓸 때는 다음과 같은 글쓰기 기법이 필요합니다. 질문에 대답하는 신속한 글쓰기, 원하는 것을 얻는 정치적 글쓰기, 먼저 질문에 대답하는 신속한 글쓰기로 글을 빨리 쓰는 방법 중에 대화를 글로 옮기는 방법이 있습니다. 가까운 동료와 대화할 때 우리는 깊이 생각하느라 한참을 뜸 들이거나 한 말을 정하지 못해서 말을 안 하는 경우는 없습니다. 일단 무슨 말이든 내뱉고 나서 생각을 정리하고, 질문을 받으면 답하면서 다음 생각으로 이어갑니다. 이 방법을 글쓰기에 그대로 적용하면 신속하게 글을 쓸 수 있습니다. 다음은 정치적 글쓰기로 윗사람에게 확정해서 말하는 것과 비슷하게, 개발자는 어떤 일을 과격하게 표현해야 할 때가 있습니다. 시스템 장애를 개발자의 야근으로 해결할 수 없을 때는 어떻게든 예산을 들여서 시스템을 확장하든 솔루션을 구매하든 해야 합니다.
◈개발자가 기술 블로그를 쉽게 쓰는 방법 3가지
첫째, 주제 의식을 버리고 소재 의식을 쓰는 것입니다. 소재 우선 글쓰기는 주제의식이 아니라 소재 의식을 갖고 쓰는 게 특정한 대상이나 상황에 대한 자기만의 관점이나 생각이나 해결 방안을 뜻합니다. 둘째, 독자 수준이 아니라 자기 수준으로 쓰는 것입니다. 글쓰기 전문가들은 다들 글을 쓸 때, 초등학생도 이해할 수 있도록 쉽게 풀어서 쓰라고 합니다. 하지만 직장에서 하는 일을 초등학생이 이해할 수 있게 풀어서 글을 쓸 수 있는 사람은 없습니다. 그리고 꼭 초등학생이 이해하기 쉽게 할 필요가 없습니다. 기술 블로그를 쓸 때 독자를 생각해서 어려운 용어를 일부러 해석해 풀어써서 글의 양을 늘려 지루함을 가질 수가 있습니다. 어려운 용어 같은 경우는 위키피디아나 세부 내용을 볼 수 있는 사이트나 문건을 링크로 걸어 두면 됩니다. 기술 블로그란 결국 실력이 비슷한 독자를 위한 것이지 독자에게 다 설명하는 것이 아니라 핵심 내용만 쓰고 나머지는 독자가 공부할 수 있게 길만 터놓는 것이 현명한 방법입니다. 마지막으로 재미있게 글을 쓰는 것입니다. 논문이나 기술 매뉴얼, 사용 설명서를 쓸 때는 자신의 경험을 녹여내거나 글의 기교를 부릴 여지가 별로 없습니다. 이런 글은 정확하고 군더더기가 없이 깔끔하지만, 글 쓰는 재미나 읽는 재미가 별로 없습니다. 그래서 경험 없고 기교도 없이 글을 쓰는 사람은 블로그에 글을 몇 번 올려보니 재미도 없고 읽는 사람도 없고, 읽은 사람이 있더라도 글에 대해 아무 반응이 없으니 얼마 못 가서 블로그를 접습니다.