[실전 API 설계] - 01. 개발자가 알아야 할 글쓰기 기본

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

문장을 구조화하는 법

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

위 문장을 개선하면 아래와 같다.

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

간단한 문장 구조로 먼저 핵심을 말하고, 부가 설명을 한다.

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

• 서술식: '~다.'로 끝나는 완전한 문장으로 구성된 글. 소설이나 신문 기사, 개발 가이드 문서에서 주로 사용
• 개조식: 신문의 헤드라인이나 어떤 사항을 나열할 때 사용. 종결 어미(~다) 대신 명사(완료, 증대 등)나 용언의 명사형(~했음)으로 끝내는 것.
• 도식: 사물의 구조나 관계, 상태를 그림이나 서식으로 보여주는 것

줄거리가 있는 설명이나 이야기는 서술식으로 쓴다. 여러 항목과 내용이 반복되거나 강조가 필요한 내용이라면 개조식으로 쓴다. 항목이나 사항의 관계를 명확히 규정하고 싶다면 도식으로 쓴다.

작성하고 보니, 상단의 정리는 개조식으로 작성했다. 위처럼 내용을 정리할 때 개조식이나 표로 나타내는 것 중에 선택하게 되는데, 좀 더 패턴이 있는 경우에는 도표를 사용하고 그게 아닐 때는 개조식으로 쓰는 것 같다.

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

글을 개조식으로 쓸 때는 글머리 기호를 반드시 쓴다. 기호는 모두 쓰임새가 달라 아무렇게나 사용하면 안 된다.

말머리 기호의 쓰임새는 글의 진술 방식으로 나뉘는데, 설명, 묘사, 논증, 서사의 네 가지가 있다.

진술 방식	상황	기호
설명	구체적으로 설명, 나열할 때. 하위 요소일수록 작고 들여쓰기 사용	■, □, ○, •, -, ⃰, ※, √
묘사	그림으로 나타낼 때 그림 안 요소나 영역을 표시	ⓐ,ⓑ,ⓒ,①,②,③
논증	논리관계(귀납, 연역, 인과, 유추, 비교, 단계 등)로 구성될 떄	∴, ∵, →, ⇒, ☞, 〉, 〈,＝
서사	순서나 단계를 나타낼 때	1, 2, 3, 가, 나, 다

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

가장 쉬운 띄어쓰기 원칙

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

• 조사는 앞 낱말에 붙인다.
• 일, 이, 삼과 같은 한글 숫자가 순서나 단계를 나타낼 때는 뒤 낱말과 붙인다.
• 숫자는 모두 뒤 낱말과 붙인다.
• '~하다'는 모두 앞 낱말과 붙인다.
• 기호는 모두 앞 낱말과 붙인다.

띄어쓰기는 알듯말듯 항상 조금씩 헷갈리는 부분이 있다. 개인적으로는 '할때', '할 때'의 경우나 '첫 번째', '첫번째'등이 헷갈리곤 했다.

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

비즈니스 문서의 따옴표는 용도가 좀 다르다.

• 책의 제목이나 신문 이름을 나타낼 때 큰따옴표 사용
• 소제목이나 작품의 제목, 상호, 법률, 규정 등을 나타낼 때 작은따옴표 사용
• 내용을 강조하거나 비교할 때 작은따옴표 사용

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

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

개발할 때는 반대되는 영어 단어를 선택할 때가 많다.

show와 hide처럼, show를 쓰고 invisible을 쓰면 안 된다. invisible의 반대말은 visible이기 때문.

• 반대말

단어	반대말
header	footer
under(미만)	over(초과)
or under(이하)	and over(이상)
before	after
open	close
input	output
import	export

• 비슷한말

중단의 의미에는 stop, end, finish, pause, suspend, hold등이 있다. 그러나 개발에서 의도는 다르다.

• stop: 잠시 중단으로 재시작 가능
• end: 완전히 중단되어 재시작 가능성이 없음
• finish: 끝난 상태
• pause: 일시 중단
• suspend: 다음 단계의 시작을 중단한 것
• hold: 어떤 의도가 있어 중단한 것

미세한 의미적 차이들이 있기는 하지만, 정확한 단어를 쓰는 것보다 중요한 것은 일관성 있고 개연성 있게 쓰는 것이다.

실제로 기능 구현시에, login, logout으로 접근했다가, 회원가입은 signup으로 사용하는 것에 일관성이 없는 게 아닌가 싶어서 다시 signin, signout으로 바꾸기도 하는 등 변수명 등을 작성할 때 일관성과 개연성에 대한 고민은 끝이 없는 것 같다. 여전히 어렵고 뿌리 깊은 프로젝트일수록 새로운 변수명 하나가 기존의 틀을 깨는 것 같은 상황이 발생할 때 고민이 깊다.

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

Windows 10의 경우, 여러 방식으로 표현된다.

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

이는 외래어 표기법과 실제로 많이 사용되는 사례가 일치하지 않는 경우다.
릴리스 노트의 release는 표기법대로면 '릴리스'지만 대부분 '릴리즈'라고 한다.
사용할 때 중요한 것은 일관성으로, 한 문서 안에서 통일하면 어색한 외래어 표기법에 맞추지 않아도 된다.

뉴스를 블로그에 정리할 때, 번역된 글을 읽으면서 가장 많이 고민하게 되는 부분 중 하나이다.

• Gemini의 한글 표기로 제미나이, 제미니처럼 다양하게 또 쓰이는 경우, 최근에는 공식적으로 제미나이로 구글 공식 명칭이 나오는데 얼마 전까지 검색을 해도 Gemini로 표기하여 어떤 발음으로 적어야 하는지 고민이 많이 되었다.
• 인명의 경우, 예를 들어 연준 이사 중 Stephen Miran. 현재는 스티븐 미런으로 많이 쓰이는 것 같은데, 초기에는 스티븐 미란으로, 그런데 발음기호는 /maɪrʌn/ MY-run 마이런으로, 스티븐 마이런으로도 언론사에서 많이 쓰였다. 처음에는 블로그에 스티븐 미란으로 썼다가 모든 문서를 마이런으로 교체했는데, 확실한 기준이 없는 게 문제 같다.