[도서] 개발자의 글쓰기

업데이트:

띄어쓰기

한글 같은 경우 조사, 순서, 숫자,하다, 기호만 붙이고 나머지는 띄어쓴다.

영어 단어 선택

서로 반대말

Positive Negative
header footer
start, restart stop
begin end

비슷한말

  • 중단
    • stop : 잠시 중단한 것이여서 언제든 재 시작 가능
    • fninish : 끝장을 본 상태여서 재시작을 고려하지 않음
    • pause : 아주 잠시 일시적으로 중단된 것이라 금방이라도 다시 시작할 것 같은 상황
    • suspend : 다음 단계의 시작을 중단한 것
    • hold : 어떤 의도가 있어서 중단한 것
  • 가져오기
    • retrieve : 검색해서 가져온다는 뜻으로 검색에 무게가 실린다면 get 대신 사용
  • 변경
    • change : 내용을 단순히 바꾸는 것
    • modify : 잘못된 것을 바로잡는 것
    • revise : 기존에 없던 새로운 정보나 아이디어를 덧붙여 기존 내용과 달라졌음을 분명히 하는 것
  • 인자
    • argument : 전달인자로 함수를 호출할 때 전달되는 값
    • parameter : 함수에 정의한 변수
  • 요소
    • property, attribute는 서로 비슷한 말이지만 언어마다 조금씩 다르게 해석된다.
  • ~해야한다
    • must : 필수 요구사항. 즉, 요구 그 자체이므로 반드시 구현돼야 한다는 의미.
    • must not : 걀코 구현(실현)돼서는 안 되는 일.
    • should : 권고 또는 권장 사항. 가능하면 지키거나 구현해야 한다. 만약 구현이 어렵다면 다른 방법을 취할 수도 있음
    • should not : 구현되지 않는 것이 더 좋다는 의미

정확한 단어를 쓰는 것도 중요하지만 그보다 더 중요한 것은 얼마나 일관성있고 개연성 있게 쓰는 것이다.

변수 이름을 잘 짓는 법

  • 긴 이름, 짧은 이름이 중요한 것이 아니라 검색 잘되는 이름이 중요
  • 복수형을 나타낼 때에는 -s 보다는 array 또는 list of를 사용하는 것이 더 좋다.
  • 약어는 보편적으로 사용하는 단어일 때 사용 ex) AWS, VIP
  • 중요한 단어를 앞에 사용

좋은 이름이 가진 5가지 특징(Smart)

  • easy to Search
  • easy to Mix
  • easy to Agree
  • easy to Remember
  • easy To Type

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

고전적 범주화를 이용하여 한 단계 상위 범주의 이름을 태그처럼 덧붙여서 사용

[안 좋은 예]

SERVER_TIMEOUT
NO_RESULT
BAD_REQUEST
SERVER_ALLOWED_REQUESTS_EXCESS

[좋은 예]

ERROR_SEVER_TIMEOUT
ERROR_NO_RESULT
ERROR_BAD_REQUEST
ERROR_SERVER_ALLOWED_REQUESTS_EXCESS

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

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

[안 좋은 예]

<html>
<head>
  <style>
    .title {font-size : 2em ...}
    ...
  </style>
  ...
<head>
<body>
  <div class="title">개발자의 글쓰기</div>
  <div class="subtitle>소프트웨어 엔지니어를 위한 테크니컬 라이팅</div>
  <div class="slogan">개발자라면 이거 모그로 쓰지 마오!</div>
</body>
</html>

[좋은 예]

<html>
<head>
  <style>
    h1.title {font-size : 2em ...}
    ...
  </style>
  ...
<head>
<body>
  <h1 class="title">개발자의 글쓰기</h1>
  <h2 class="title">소프트웨어 엔지니어를 위한 테크니컬 라이팅</h2>
  <p class="title">개발자라면 이거 모그로 쓰지 마오!</p>
</body>
</html>

이름 하나만 지으면 기존 태그와 조합해 h1.title, h2.title, p.title과 같이 사용할 수 있다.

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

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

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

뇌는 감각적인 것을 좋아한다. 감각적인 단어는 그렇지 않은 단어보다 기억하기가 쉽다. 특히 시각적으로나 청각적으로 완결된 단어가 그렇지 않은 단어보다 더 잘 기억된다.

예를 들어 직원 기본 정보를 클래슬 만든다고 가정하였을 때 Basic Information of Employee로 번역한 뒤 각 단어 첫 글자만 따서 BIE라고 만들 수 있다. 하지만 전치사 of의 첫 글자를 붙여서 BIOE라고 만들 수도 있다.

  • BIE : 바이? 비이? 바이이?
  • BIOE : 바이오 이!

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

예를 들어 KakaoMessageTemplateButtonObject를 줄여서 KMTButtonObject라고 이름 짓는다고 할 때 사람들은 Button을 Buton으로 잘못 타이핑하는 경우가 많다. 그래서 차라리 KMTBtnObject로 바꾸는 것도 나쁘지 않다.

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

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

변수

[안 좋은 예]

// 스크린 최대 높이를 480으로 지정함
int h = 480

[좋은 예]

int screenHeightMax = 480

JSON

[안 좋은 예]

"success" : [ // 구독자 추가 성공
],
"update" : [ // 아마 았는 구자, 나머지 필드를 업데이트함.
],
"failDeny" : [ // 수신 거부 상태의 구독자, 추가하지 않음
],
"failWrongEmail" : [ // 잘못된 이메일 주소 형식, 추가하지 않음
],
"failUnown" : [ //   없는 오류로 추가하지 않음
],

[좋은 예]

"created" : [
],
"updatedInformationExceptEmail" : [
],
"noCreatedBecauseUnsubscriber" : [
],
"noCreatedBecauseWrongEmail" : [
],
"noCreatedBecauseUnknownError" : [
],

에러 메시지 쓰기

사용자 에러 메사자

  • 에러 내용 : 오류로 인한 문제와 종류
  • 에러의 원인 : 오류를 발생시킨 직접적이고 근본적인 원인
  • 에러 해결 방법 : 사용자가 오류를 해결할 가장 쉽고 빠른 방법

앞 예문을 정리하면 다음과 같다.

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

버튼의 순서

버튼의 확인, 취소 순서는 확인-취소, 취소-확인 순서 문제보다 일관성을 가지는 것이 중요하다. 그래야 사용자 경험이 어긋나지 않는다.

체인지 로그 작성하기

체인지 로그가 너무 간단하면 한 일이 없어 보이고 너무 자세히 쓰면 아무도 읽지 않아 쓸모가 없다.

체안지 로그를 적절한 양으로 쓰려면 일단은 최대한 많이 쓴 후 아래의 단계를 거친다.

  1. 선정하기
  2. 분류하기
  3. 요약하기
  4. 종합하기

1단계: 선정하기

회사가 말하고 싶다 개발자가 말하고 싶다 독자가 듣고 싶다 순위 수준 예시
O O O 1순위 자세히 인공 지능 추천 추가
O O X 2순위 간단히 대용량 네트워크 증설
O X O 3순위 간단히 UI 개선
O X X 4순위 주석 면책 조항, 정책 변경
X O O 5순위 참고 작업 과정, 레퍼런스
X O X 삭제 - 성과가 낮은 오류 수정
X X O 삭제 - 경쟁력 없는 기능 추가
X X X 삭제 - 사소한 오류 수정

2단계: 분류하기

체인지 로그끼리 묶을 때 두 가지 방법이 있다.

  1. 개발 관점에서 비슷한 체인지 로그끼리 묶는 것, 독자가 개발자인 경우에 유용하다.
    • 새로운 기능 추가, 기능 개선, 오류 수정
  2. 사용자 관점에서 비슷한 것끼리 묶는 것

3단계: 요약하기

서술식 문장을 개조식 문장으로 바꾼다. 개조식 문장으로 만들려면 불필요한 부사나 형용사, 조사나 어미를 없애고, 정확하고 적절한 단어로 대체한다.

변경 전


  • 게임 준비
    • 미리 보기에서 간혹 리부팅되는 문제를 해결했습니다.
    • 빈 게임방을 자동으로 검색하는 기능을 추가했습니다.
    • 닉네임을 만들 때 특수 문자를 입력하는 기능을 추가했습니다.
  • 게임 중
    • 고해상도 폰에서 아이콘이 찌끄러지는 오류를 수정했습니다.
    • 가로/세로 화면 전환 시 하단 메뉴가 사라지는 오류를 수정했습니다.
    • 애니메이션 스티커가 갑가지 멈추는 오류를 수정했습니다.
  • 게임 종료
    • 최근 기록이 상위에 올라오도록 개선했습니다.
    • 게임 종료 후 바로 순위롤 볼 수 있도록 개선했습니다.
    • 용량이 큰 사진을 등록할 때 휴대전화 메모리 사용을 최소화하도록 등록 방식을 개선했습니다.

변경 후


  • 게임 준비
    • 미리 보기 리부팅 문제 해결
    • 빈 게임방 자동 검색 기능 추가
    • 닉네임을 만들 때 특수 문자 입력 기능 추가
  • 게임 중
    • 고해상도 폰에서 아이콘이 찌끄러지는 오류를 수정
    • 가로/세로 화면 전환 시 하단 메뉴가 사라지는 오류를 수정
    • 애니메이션 스티커가 멈추는 오류를 수정
  • 게임 종료
    • 최근 기록이 상위에 올라오도록 개선
    • 게임 종료 후 바로 순위를 볼 수 있도록 개선
    • 용량이 큰 사진을 등록할 때 휴대전화 메모리 사용 최소화

4단계: 종합하기

릴리스 내용 전체를 종합해서 한 문장을 만들고 그것을 체인지 로그 첫 줄에 적어야 한다.


사용자 편리성 개선
  • 게임방에 더 빨리 입장
  • 게임 결과 바로 확인

  • 게임 준비
    • 미리 보기 리부팅 문제 해결
    • 빈 게임방 자동 검색 기능 추가
    • 닉네임을 만들 때 특수 문자 입력 기능 추가
  • 게임 중
    • 고해상도 폰에서 아이콘이 찌끄러지는 오류를 수정
    • 가로/세로 화면 전환 시 하단 메뉴가 사라지는 오류를 수정
    • 애니메이션 스티커가 멈추는 오류를 수정
  • 게임 종료
    • 최근 기록이 상위에 올라오도록 개선
    • 게임 종료 후 바로 순위를 볼 수 있도록 개선
    • 용량이 큰 사진을 등록할 때 휴대전화 메모리 사용 최소화

Semantic Versioning

  • 버전은 X.Y.Z의 형태로 한다.
    • X는 Major
    • Y는 Minor
    • Z는 Patch
  • X가 0인 것은 초기 내부 개발에서만 사용하고, 최초 공개 API는 1.0.0이어야 한다. X는 기존 버전과 호환되지 않는 변화가 있을 때만 1씩 올린다.

  • Y는 기존 버전과 호환되는 새로운 기능이 추가가 되었을 때 1씩 올린다. 참고로 개발의 시작은 0.1.0이다. 개발의 시작은 새로운 기능의 시작이기 때문이다.

  • Z는 기존 버전과 완전히 호환되먄서 작은 규모의 패치가 있을 때 1씩 올린다.

  • 정식 배포 전에 사전 배포가 필요할 때는 Z 다음에 붙임표(-)로 구분하고 적절한 식별자를 적는다. 예를 들어 알파 버전이면 1.0.0-alpha 로 쓴다.

  • 일단 배포된 버전은 변경해서는 안 된다. 변경이 있다면 무조건 버전을 올려야 한다.

장애 보고서

장애 보고서 특징

  1. 장애 보고서는 개발자가 원할 때 쓸 수 없다.

  2. 장애의 1치 원인은 대부분 다른 원인의 결과다.
    • 장애의 원인을 정확히 알아내려면 원인의 원인을 계속 찾아 나가야 한다. 더는 원인을 찾을 수 없을 때 그 원인이 장애의 최초 원인이다.
  3. 장애 보고를 받은 윗사람은 대배분 개발자가 아니다.

  4. 장애를 해결했다고 해서 100% 해결한 것은 아니다.

개발 가이드 작성하기

서비스 매뉴얼이나 개발 가이드의 첫 문단은 서비스 개념을 설명하는 자리다.

개발자가 독자에게 서비스 개념을 설명할 때는 범주, 용도, 특징 순으로 쓰는 것이 좋다.

예시)

(범주) Amazon Simple Storage Service(Amazon S3)는 인터넷 스토리지 서비스입니다.

(용도) Amazon S3를 사용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장하고 검색할 수 있습니다.

(특징) AWS Management Console의 간단하고 직관적인 웹 인터페이스를 통해 이러한 작업을 수행할 수 있습니다.

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

범주는 서비스를 소개하거나 설명하는 첫 문장인 만큼 정확하고 적절하게 정해야 한다. 가장 좋은 방법은 여러 경쟁사가 사용하는 보편적인 서비스 범주를 따라하는 것이다.

예를 들어 사람들이 등록한 아이디어에 여러 사람이 투자하는 서비스 이름을 ABC라고 할 때 경장사 웹사이트의 설명이 한결같이 크라우드 펀딩 이란 범주를 사용했다면 개발자는 ABC를 소개하는 첫 문장에 이 범주를 사용하면 된다.

ABC는 크라우드펀딩 서비스입니다.

  • 경쟁사보다 전반적으로 발전한 서비스라면

ABC는 보다 발전된 클라우드펀딩 서비스입니다. ABC는 클라우드 펀딩 2.0 서비스입니다.

  • 특정 사용자를 위한 서비스라면

ABC는 개발자를 위한 클라우드펀딩 서비스입니다. ABC는 주부만을 위한 클라우드펀딩 서비스입니다.

용도를 범주의 핵삼 기능으로 기술

첫 문단의 첫 문장에 범주가 사용된다면 첫 문단의 두 번째 문장은 독자 관점의 용도를 주로 적는다.

Amazon S3를 사용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장하고 검색할 수 있습니다.

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

범주와 용도에는 보편적인 내용을 적는다. 하지만 특징은 차별화하는 내용을 적어야 한다.

  • 장점 : 자기가 할 수 있는 여러가지 중에서 특별히 잘하는 것
  • 강점 : 경쟁 서비스와 비교해서 잘하는 것

  • 장점이자 강점인 것 하나를 쓴 예

ABC 서비스는 최고의 안정성을 제공합니다.

  • 장점이자 강점을 한 문장에 같이 쓴 예

ABC 서비스는 간단하고 직관적인 웹 인터페이스와 안정적인 서비스를 제공합니다.

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

제안서에서 개발자는 주로 기술 부문을 쓴다. 제안서의 기술 부문은 대부분 그림과 표로 구성된다. 하지만 본질은 단순히 그림과 표가 아니라 제안 요청서의 요구 사항을 반영하는 것이다.

첫째, 제안 요청서 분석

제안요청서를 제대로 분석하는 것이다. 제안 요청서는 제안서 작성의 시작이다. 거의 모든 문제와 답은 제안요청서에 들어있다.

제안 요청서에는 목표 시스템, 하드웨어 구성도, 소프트웨어 구성도, 요구 기능, 구매 소프트웨어 목록 같은 것이 이미 들어 있다. 따라서 개발자는 일부문만 보고 그림을 그려서는 안 된다.

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

둘째, 논리적 완결성

항목을 논리적으로 완결하는 것이다. 누구도 제안서를 소설 읽듯이 첫 글자부터 순서대로 읽지 않는다. 사업 담당자나 심사위원은 자기와 관련이 있거나 관심 있는 항목, 또는 특정 페이지만 골라 읽는다.

시스템 구성도라는 항목을 작성한다면, 이 항목 안에는 시스템 구성에 관한 고객의 요구, 고려 사항, 구성 전략, 구성 목표, 구성의 특장점, 기대 효과가 들어가야 한다. 그래야만 시스템 구성도를 그렇게 그린 이유를 논리적으로 납득할 수 있다.

요구 사항

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

  2. 요구 사항은 반드시 변한다. 그러니 최초의 요구사항은 단지 참고사항일 뿐이다. 요구사항이 끊임없이 변한다는 것을 이해해야 개발자가 대응할 수 있다.

요구사항은 개발자 관점과 고객 관점이 다르다. 가장 좋은 것은 개발자의 시간을 적게 쓰면서도 고객의 만족도가 높은 기능을 먼저 잘 개발하는 것이다.

기술 블로그 작성하기

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

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

주제 의식은 많은 사람에게 보편적인 주제를 선택해서 더 많은 사람에게 주제 의식을 퍼뜨리는 것이지만, 소재 의식은 독자와 상관없이 대상이나 상황에 맞닥뜨렸을 때부터 그 대상이나 상황에서 벗어날 때까지 겪은 일을 담담하게 정리해서 얘기할 뿐이다.

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

개발자가 기술 블로그를 쓸 때는 독자를 생각해서 어려운 용어를 일부러 해식해 풀어쓰거나 쉬운 용어로 바꿀 필요가 없다. 원래 사용하는 용어로 그냥 표기하되 필요하다면 용어를 정의한 위키피디아 페이자나 세부 내용을 볼 수 있는 사이트나 문건을 링크로 걸어두면 된다.

독자에게 다 설명하는 것이 아니라 핵심 내용만 쓰고 나머지는 독자가 공부할 수 있게 길만 터놓는 것이 현명한 방법이다. 그래야 개발자도 자기가 쓰려는 글의 본질에 집중할 수 있다.

셋째, 재미있게 글을 쓰자

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

예를 들어 위키피디아의 설명에는 없는 경험과 기교가 나무위키에 있다. 그래서 나무위키가 위키피디아보다 일ㄷ는 재미가 있다. 좋은 기술 블로거는 개발자의 경험에서 우러나오는 내용을 적절한 글쓰기 기교로 녹아낸 것이다.

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

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

개발 과정과 걀과를 다룬 개발기를 쓸 때는 무엇보다 목차를 잘 구성해야 한다.

개발자가 가장 잘 쓸 수 있는 내용은 본문이다. 목차를 정했으면 머리말부터 쓰지 말고 본문부터 쓰자. 본문을 쓰고 나면 맺음말을 쓰자. 머리말은 맨 마지막에 블로그에 올릴 때 생각나는 대로 간략히 적는 것이 좋다.

예시)

  1. 머리말 서비스의 설명
    1. 서비스의 설명
    2. 개발의 필요성
  2. 본문
    1. 아키텍처나 알고리즘
    2. 개발 모델(최종 루트)
    3. 개발 과정에서 발견한 문제와 해결 방법(경험 루트)
    4. 남은 작업
  3. 맺음말
    1. 소감이나 회고

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

개발에서 술은 새로운 기술을 자세하게 또는 비유해 설명한 것, 비슷한 용어를 비교해 풀이 한 것, 에러 해결 방법 등이 여기에 해당한다.

예시)

  • GET과 POST의 차이
  • MySQL Ascending index vs. Descending index
  • Webpack4의 Tree shaking에 대한 이해

예를 들어 GET과 POST의 차이를 설명한다고 한다고 할 때..

사람은 어떤 사물을 그 자체를 인식하기보다는 다른 사물과 비교하면서 인식 할 때 더 잘 이해한다. 하지만 원전은 사물 하나하나를 설명할 뿐이지 두 사물 사이의 공통점이나 다른 점을 뚜렷이 밝히지는 않는다. 그래서 원전의 두 용어나 대상을 비교하면서 풀이하는 것이 바로 술의 역활이다.

위를 토대로 목차로 작성하면..

  1. HTTP
  2. GET
  3. POST
  4. GET과 POST의 차이
  5. 참고

위 목차를 잘 보면 실제로 개발자가 쓴 글은 4장 뿐이다. 이렇게 원전의 내용을 먼저 쓰고 비교한 내용을 추가하는 것만으로도 기술 블로그를 쉽게 쓸수 있다.

편: 순서를 요약하여 쓰자

프로그램 설치나 설정 순서, 개발 방법, 튜토리얼, 개발자 컨퍼런스 후기 같은 것이 여기에 해당된다.

예시)

  • 사용하면서 알게 된 Reator, 예제 코드로 살펴보기
  • ES2015 단위 테스트 환경 구축하기
  • 간단하게 구축해 보는 Java Script 개발 환경
  • Ubuntu의 apt-get 명령어 정리

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

예시)

  • Git 저장소 만들기
  • Github에 이슈 등록하기
  • Node.js 와 np,, Yarn
  • 프로젝트 생성
  • package.json 파일과 패캐지 관리
  • yarn.lock 파일과 패키지 일관성
  • 프로젝트 공유
  • README.md 파일 활용

위 내용을 다음과 같이 정리

  1. Git과 Github를 활용한 협업 공간으로 개발 시작하기
    • Git 저장소 만들기
    • Github에 이슈 등록하기
  2. Node.js와 Yarn으로 개발 환경 설정하기
    • Node.js 와 npm, Yarn
    • 프로젝트 생성
    • package.json 파일과 패캐지 관리
    • yarn.lock 파일과 패키지 일관성
    • 프로젝트 공유
    • README.md 파일 활용

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

집은 여러 사람의 견해나 흩어진 자료를 한데 모아 정리하는 것이다.

집은 내용을 많이 쓰는 것이 아니라 핵심만 간결하게 정리한 것이다. 기술 블로그에서는 명령어 모음, 팁, OO 규칙 같은 것이 집에 해당한다.

예시)

  • 자바스크립트 정규표현식 코딩법
  • 스크롤과 관련된 CSS 속성 3가지
  • 좋은 코딩을 위한 13가지 간단한 규칙

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

장점

  1. 글의 완성도가 높아진다.
  2. 지식을 보편화할 수 있다.
  3. 팀 회고를 할 수 있다.
  4. 심리적 안정감을 느낀다.

태그:

카테고리:

업데이트:

댓글남기기