개발자를 위한 글쓰기

테크니컬 라이팅에 계속 관심이 있어서 조금씩 찾아서 읽어보는 중. 구글의 테크니컬 라이팅 문서가 문장을 어떻게 쓸 것인가에 대한 이야기라면 이 책은 글을 어떻게 쓸 것인가에 대한 이야기다. SI 위주긴 하지만 ‘어떻게’에 초점을 맞춘 내용들이 많아서 배울 점이 많다. 특히 Release Note 작성하는 방법에 관한 꼭지는 너무 재밌었다. 다만 마지막의 마지막에 예시로 나무위키를 든게… 좀 그랬음. 의도는 충분히 알겠으나 그럼에도 불구하고 예시로 들것과 말것이 있다고 생각한다. 이거때문에 어디 가서 추천하고 다니지는 못할듯…

• 계층은 3차원 입체의 높이를 뜻한다. 무대는 객석보다 항상 높다. 높은 곳의 의자는 낮은 곳의 의자보다 크고 고급스럽다. 문서에서 계층은 굵기, 모양, 밑줄, 줄 간 거리 등으로 포현된다. 개발자가 사용하는 개발 툴은 다음 예문과 같이 위치는 맞출 수 있지만 계층을 맞출 수는 없다. 개발자가 일반 문서를 쓸 때는 위치는 과도하게 맞추지만 계층은 거의 표현하지 않는 경향이 있다. 그래서 개발자가 쓴 문서를 기획자나 관리자가 보면 마치 메모장으로 문서를 작성한 느낌이 든다.
• 동사 get은 어떤 값을 돌려받아서 반환하는 함수에 사용한다. 반면 return은 함수 이름에 쓰지 않는다. return은 주로 함수 안에서 제어에 쓰기 때문이다. 게다가 return의 주체(=주어)는 객체이므로 함수에 return을 쓰면 자기가 자기에게 돌려주는 이상한(?) 루프에 빠진다.
• get과 비슷한 단어로 retrieve가 있다. retrieve는 검색해서 가져온다는 뜻이다. 검색에 무게가 실린다면 retrieve를 쓰는 편이 낫다. acquire는 독점한다는 뜻이다. 다른 함수가 가져가지 못하게 독점하고자 할 때는 acquire를 쓰자. fetch는 현재 값을 가리키는 포인터가 다름 값으로 이동한 것을 가져온다는 뜻이다.
• get과 비슷한 것 같지만 set은 완전히 다른 용도다. set은 값을 변경하거나 설정하는 함수에 쓴다. 초기화 설정이라면 init을 쓰는 것도 좋은 방법이다. create와 register도 비슷하지만 전혀 다른 역할을 한다. register는 이미 정해진 틀에 값을 집어넣는 것이다. create는 정해진 틀이 없으므로 먼저 틀을 만들 때 쓴다.
• 수정을 나타내는 change, modify, revise도 의도가 다른 말이다. change는 내용을 단순히 바꾸는 것이다. modify는 잘못된 것을 바로잡을 때 쓴다. revise는 기존에 없던 새로운 정보나 아이디어를 덧붙여 기존 내용과 달라졌음을 분명히 할 때 사용한다.
• parameter는 매개변수로, 함수에 정의한 변수를 뜻하고 argument는 전달 인자로 함수를 호출할 때 전달되는 값을 의미한다. attribute는 HTML에서 태그 안에 속성을 넣을 때 사용되는 요소다. 하지만 이 요소를 HTML DOM에서 가리킬 때는 property라고 한다. attribute와 property는 언어마다 조금씩 다르게 해석된다.
• 개발자에게는 별거 아니지만 독자에게는 중요한 것이 있다. 반대로 개발자는 큰 노력을 들였지만 독자가 보기에는 사소한 것일 수도 있다. 따라서 다음과 같이 개발자의 노력과 독자의 관심을 기준으로 표를 만들어보면 체인지 로그 순위를 좀 더 전략적으로 선정할 수 있다.
• 장애가 발생할 확률이 10%도 안 되는데 90%인 양 호들갑을 떨거나, 장애 발생 확률이 99%나 되는데도 별일 아니라고 보고하면 안 된다. 그런 보고는 모두 허위보고이기 때문이다. 정치적 글쓰기는 자신의 처지를 따지거나 상사 눈치를 살펴 가면서 얼버무리듯 보고하는 것이 아니다. 개발자야말로 정치적으로 글을 쓰고 보고해야 한다.
• 개발 가이드 문서의 시작 - 1. 범주 2. 용도 3. 특징
• 글이 그림과 같이 있으면 글과 그림이 같은 용어를 사용하는지 꼭 확인해야 한다. 글을 먼저 쓰고 그림을 나중에 그리든, 그림을 먼저 쓰고 글을 나중에 쓰든 상관없다. 같은 것을 다르게 표현하는 순간 독자는 헷갈리기 시작하고 그 결과는 에러로 나타난다.
• 거칠게도 공손하게도 쓰지 말자
• 문제의 답과 거리를 좁혀서 쓰자
• 기업의 기술 블로그를 광고 매체로 생각해야 한다. 광고 매체에 광고비를 집행하듯이 기술 블로그에도 광고비를 들여야 한다. 타깃 독자에게 홍보하고 검색엔진에 잘 검색되게 하고 최신 트렌드를 추적해 태그를 달아야 한다. 기술 블로그 운영자가 이런 일을 제대로 열심히 할 수 있도록 필요한 비용을 투자해야 한다.
• 개발자의 글쓰기 원칙이나 수준을 정하기 전에 회사의 글쓰기 문화를 먼저 정의해야 한다. 회사의 글쓰기 문화가 없다면 그것부터 먼저 정해야 개발자들이 글을 어떻게 쓸지 알 수 있다. 개발언어가 프로그램보다 먼저인 것처럼, 회사의 문화가 개발자의 글쓰기보다 먼저다.