1-10. Punctuation
Google Technical Writing Course - 1
다양한 구두점에 대한 이야기.
아래 내용들을 다룬다.
Commas
여기서 다루는 콤마의 역할은 크게 3가지이다.
1. 문장의 호흡 조절 (pause)
2. 항목들 간의 구분 (embedded lists)
3. 구절간 구분 (조건문, 간단한 정의나 여담 등)
2번의 경우, 마지막 항목 앞에 붙는 serial comma (oxford comma)에 대해서는 사용 여부에 대한 논란이 있으나, 기술 문서에서는 명확한 구분을 위해 사용하는 것을 권장한다고 한다. 예를 들면, 아래 문장에서 "and Javascript" 앞에 콤마가 붙어 있다.
Our company uses C++, Python, Java, and JavaScript.
그러나 더 명확한 구분을 위해서는 리스트 사용을 더 권장한다.
또한, 독립된 두 문장에 대해서는 콤마로 잇는 대신 마침표를 사용해 확실히 구분하는 것이 좋다.
Exercise
적당한 위치에 콤마 넣기.
먼저 해본 후에 빠뜨린 부분을 볼드체로 추가했다.
Protocol Buffers, sometimes known as protobufs, are our team's main structured data format. Use Protocol Buffers to represent, store, and transfer structured data. Unlike XML, Protocol Buffers are compiled. Consequently, clients transmit Protocol Buffers efficiently, which has led to rapid adoption.
Semicolons
세미콜론(;)을 사용하려면 아래 3가지 조건을 만족해야 한다.
1) 이어지는 문장들 간 주제가 연관되어 있을 것.
2) 세미콜론 앞뒤 문장을 뒤바꾸었을 때도 의미가 통할 것.
3) 세미콜론 앞뒤 문장이 각각 문법적으로 완전할 것.
예를 들어 세미콜론을 사용한 아래 문장은 위의 3가지 조건을 모두 만족한다.
(원문) Rerun Frambus after updating your configuration file; don't rerun Frambus after updating existing source code.
→ 설정 파일을 업데이트한 후에 Frambus를 다시 실행하라; 기존 소스 코드를 업데이트한 후에는 Frambus를 재실행하지 마라.
(앞뒤 바꿨을 때) Don't rerun Frambus after updating existing source code; rerun Frambus after updating your configuration file.
→ 기존 소스 코드를 업데이트한 후에는 Frambus를 재실행하지 마라; 설정 파일을 업데이트한 후에 Frambus를 다시 실행하라.
아래 예시의 경우 세미콜론 뒷 문장이 완전하지 않으므로, 세미콜론보다는 콤마를 사용하는 것이 맞다.
Rerun Frambus after updating your configuration file; not after updating existing source code.
→ Rerun Frambus after updating your configuration file, not after updating existing source code.
항목들 간의 연결은 세미콜론 대신 콤마나 리스트를 사용하는 것이 당연하기에, 예시는 패스.
한편, 세미콜론 뒤에 전환어(however, therefore 등)가 올 때는 콤마를 함께 사용해야 한다.
아래 예시를 참고하자.
Frambus provides no official open source package for string manipulation; however, subsets of string manipulation packages are available from other open source projects.
Even seemingly trivial code changes can cause bugs; therefore, write abundant unit tests.
Exercise
하기 3가지 문장 중, 2번째 문장만 두 문장을 세미콜론으로 연결하기에 적합하다.
1번의 경우 두 문장간 연관성이 적고, 3번의 경우 항목들의 나열이기 때문이다.
1. Python is a popular programming language. The C language was developed long before Python.
2. Model learning for a low value of X appears in the top illustration. Model learning for a high value of X appears in the bottom illustration.
→ Model learning for a low value of X appears in the top illustration; Model learning for a high value of X appears in the bottom illustration.
3. I'm thankful for my large monitor, powerful CPU, and blazing bandwidth.
Em dashes
'작대기'라고도 부르던 문장 부호가 길이에 따라 3종류나 있었다니...
Em dash는 가장 긴 '작대기'로, 일반 콤마보다 조금 더 긴 호흡이 필요할 때나 삽입구를 넣을 때 사용된다.
따라서 콤마와 호환이 가능하며, 그 둘을 구별하는 특별한 기준은 없다.
즉 문장 스타일이나 톤에 따라 직관적으로 선택하면 된다.
한편, 처음 언급한 대로 길이에 따라 em dash 뿐만 아니라 en dash와 hyphen도 있다.
en dash에 대해서는 별 설명 없이 Google Style Guide에서 권장하지 않는다는 말이 있어서 별도로 찾아봤다.
보통 '6–10kg', 'June–August' 처럼 범위를 나타내는 데 쓰이며, 이 경우 전치사 to로 대신할 수 있다. Google Style Guide에서 권장하는 것은 en dash 대신 to를 사용하는 방법이다.
hyphen의 경우 2개 이상의 단어를 하나의 복합어로 연결할 때 사용된다.
예를 들어 self-attention, n-gram 등이 있다.
다만 3단어 이상의 경우 첫번쨰와 두번째 사이에는 hyphen을 사용하지만, 두번째와 세번째 사이에는 사용하지 않는다. 예를 들어 Decision-making system, Floating-point feature 등이 그러하다.
Colons
뒤에 리스트나 표가 나올 때 콜론을 사용한다.
아래는 각각 bulleted list, embedded list가 나올 때 콜론을 사용한 예시이다.
Consider the following important programming languages:
Python
Java
C++
Consider the following important programming languages: Python, Java, and C++.
Parentheses
괄호는 부가 정보나 여담을 담을 때 사용된다.
즉 괄호 안의 내용은 중요도가 낮다고 여겨지며, 기술 문서에서는 괄호 사용을 최소화하는 것이 권장된다.
괄호의 마침표에 대한 표준 규칙은 다음과 같으나, 항상 명확하게 지켜지는 것은 아닌듯하다.
괄호 안의 내용이 완전한 문장이면 마침표는 괄호 안에 사용한다.
괄호 안의 내용이 불완전한 문장이면 마침표는 괄호 밖에 사용한다.
예시는 아래와 같다.
(Incidentally, Protocol Buffers make great birthday gifts.)
Binary mode relies on the more compact native form (described later in this document).
출처 : https://developers.google.com/tech-writing/one/punctuation
여기까지 해서 Technical Writing One의 Pre-Class는 끝이다.
뒤에 Markdown 파트가 있기는 하지만, markdown이 무엇인지 정도만 가볍게 언급하고 넘어가기에 따로 정리는 하지 않으려고 한다. 대신 아래에 Markdown 및 Pre-class summary 링크만 첨부한다.
- Markdown : https://developers.google.com/tech-writing/one/markdown
- Summary : https://developers.google.com/tech-writing/one/summary
이 다음은 In-class인데, 실습 활동으로 이뤄져 있다.
라이브 세션에 참가했으면 좋았겠지만, 이미 놓쳤으니 혼자 문제 풀어보고 따로 정리해서 남길 예정.
