[개발자의 글쓰기] 1장. 개발자가 알아야 할 글쓰기 기본

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

   1. 문장을 구조화하는법

      • 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 된다.(한 문자의 길이가 길지 않아야 좋다!)
        • 나쁜 예 : 색상 RGB 값을 각각 사용하기 때문에 입력 데이터는 3차원 벡터다.
        • 좋은 예 : 입력데이터는 3차원 벡터다. 색상 RGB 값을 각각 사용하기 때문이다.

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

      • 서술식 : '~다'로 끝나는 완전한 문장으로 구성된 글을 말한다. 무엇을 설명하거나 논증할 때 주로 사용하는 방식이다.(지금의 설명글도 서술식이다.)
      • 개조식 : 신문의 헤드라인을 쓰거나 어떤 사항을 나열할 때 사용한다. 종결어미('다',...)대신 명사나(' 완료', '~ 증대', ...) 용언의 명사형('~ 했음',...)으로 끝내는 것을 개조식이라 한다. 주로 릴리스 문서나 장애보고서를 쓸 때 개조식으로 쓴다.
      • 도식 : 사물의 구조나 관계, 상태를 그림이나 서식으로 보여주는것이다. 일반적으로 표를 의미한다. 표(table), 도표(graph/chart)등도 포함된다.

    줄거리가 있는 설명이나 이야기 -> 서술식  
    여러가지 종류의 항목과 내용이 반복 혹은 서술식에서 강조가 필요한내용 -> 개조식  
    각 항목이나 사항의 관계를 명확히 규정 필요 -> 도식

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

   글의 진술 방식은 설명, 묘사, 논증, 서사의 네가지가 있다.

   • 설명 : 내용을 구체적으로 설명하건 나열할 때 ■, □, ○, *, -, ※ 등을 사용한다. 하위 요소로 갈수록 부가설명이 되면서 중요도가 낮아지므로 크기가 작아지고 들여쓰기를 해야한다.

   • 묘사 : 내용을 그림으로 나타낼 때 그림안에 어떤 요소나 영역을 표시하기 위해서는 ⓐ, ⓑ, ⓒ, ①, ②, ③ 등의 원형문자를 사용한다.

   • 논증 : 내용이 논리관계(귀납, 연역, 인과, 유추, 비교, 단계 등)로 구성될 때는 ∴, ∵, ⇒, →, >, <, = 등을 사용한다.

   • 서사 : 순서나 단계를 나타낼 때는 1,2,3,가,나,다 등 숫자나 문자를 사용한다.

3. 단락을 구조화 하는 위계

   비즈니스 문서에는 문단과 문단 사이에 위계가 있어야 한다. 이때 위계는 위치와 계층을 합한 말이다.

   • 나쁜 예 : p.32 참고
   • 좋은 예 : p.33 참고

   개발자가 사용하는 개발툴은 위치는 맞출 수 있지만 계층을 맞출 수는 없다. 그래서인지 일반 문서를 쓸 때 위치는 과도하게 맞추지만 계층은 거의 표현하지 않는 경향이 있다. 계층이 없는 문서를 읽고 이해하는데는 시간이 오래 걸리므로, 비즈니스 문서에는 반드시 계층을 표현하도록 하자!!

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

   1. 가장 쉬운 띄어쓰기 원칙

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

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

      • 한글 따옴표 규정 : 큰따옴표는 글에서 직접 대화를 표시하거나 말이나 글을 인용할 때 사용한다. 작은따옴표는 인용한 말 안에 있는 인용한 말, 또는 마음속으로 한말을 쓸때 사용한다.
      • 비즈니스 문서 : 큰따옴표는 책의 제목이나 신문 이름을 나타낼때 쓴다. 작은 따옴표는 소제목이나 예술 작품의 제목, 상호, 법률 규정 등을 나타낼 때와 어떤내용을 강조하거나 비교해서 드러내야 할 때 쓴다.
      • 이번에 출간된 "개발자의 글쓰기"를 참고했음.
      • 이번 릴리스는 '개인정보 보호법'을 준수함.
      • 이 시점에서 중요한것은 '창의'가 아니라 '열정'임.

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

   • header <-> footer
   • under(미만) <-> over(초과)
   • or under(이하) <-> and over(이상)
   • before <-> after
   • open <-> close
   • input <-> output
   • import <-> export
   • stop : 잠시중단할때 사용
   • end : 완전히 중단하여 재시작할 가능성이 없을때 사용.
   • finish : 완전히 끝나서 재시작을 고려할 필요가 없을때 사용.
   • pause : 아주 잠시 일시적으로 중단될때 사용.
   • suspend : 다음 단계의 시작을 중단할때 사용.
   • hold : 어떤 의도가 있어서 중단할때 사용.
   • get : 어떤 값을 돌려받아서 반환하는 함수에 사용.
   • retrieve: get과 비슷하게 쓰이지만 어떤 값을 검색해서 반환하는것에 무게가 실린다면 사용.
   • acquire : get과 비슷하게 쓰이지만 다른 함수가 가져가지 못하게 독점하고자 할때 사용.
   • fetch : get과 비슷하게 쓰이지만 현재값을 가리키는 포인터가 다음값으로 이동(moveNext)한 것을 가져올때 사용.
   • set : 값을 변경하거나 설정하는 함수에 사용.
   • init : set과 비슷하게 쓰이지만 초기화를 할때 사용.
   • create : 정해진 틀이 없을때 먼저 틀(객체)를 만들때 사용.
   • register : 이미 정해진 틀에 값을 집어 넣을때 사용.
   • change : 수정을 나타내는 단어. 내용을 단순히 바꿀때 사용.
   • modify : 수정을 나타내는 단어. 잘못된것을 바로잡을때 사용.
   • revise : 수정을 나타내는 단어. 기존에 없던 새로운 정보나 아이디어를 덧붙여 기존 내용과 달라졌음을 분명히 할 때 사용.
   • parameter : 매개변수로, 함수에 정의한 변수(variable)를 뜻함.
   • argument : 전달 인자로, 함수를 호출할 때 전달되는 값(value)을 뜻함.
   • must : 필수 요구사항
   • must not : 절대 구현되서는 안되는 사항
   • should : 권고 혹은 권장 사항
   • 한글라이즈 (외국어 -> 한글 표기) : https://hangulize.org