개발자의 글쓰기 - 문장과 단락을 구조화하는 법

저자 : 김철수

 

들어가며

---

개발자의 글쓰기

 개발자로서 직업인으로서 갖추어야 할 글쓰기 방법에 대해 쉽게 알려주는 책이다. 토비의 스프링같이 완독 자체로도 의미있는 그런 난이도 있는 책을 읽고 난 뒤 머리를 식힐겸 읽어도 좋을 책이다. 신입때 이전 직장에 있을 때는 개발자가 코드만 잘 짜면 되는줄 알았다. 개발이란 작업을 코드로 구현하는 위주로 접근했던 때이다. 이직을 하고 난 뒤 생각이 바뀌어 개발에 대해 다시 고민하기 시작했고, PO, 디자이너, 동료 개발자, QA 등 제품과 관련된 모든 이해관계자와의 소통, 업무 지식 문서화와 같은 소프트 스킬이 개발의 반을 이룬다는 것을 깨달았다. 소프트 스킬이 부족하면 업무 성과가 나올수가 없다. 이번 책은 소프트 스킬 중 문서를 잘 작성하기 위한 기술적인 가이드를 해준다.

 변수 네이밍과 기술 블로그는 특별한 느낌을 받지 못했고, 기본적인 글쓰기 노하우와 릴리스 노트, 장애 보고서는 인상깊어 이 내용을 위주로 정리하였다.

 

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

---

문장 구조화 

문장을 쉽게 쓰려면 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 좋다.

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

첫번째 문장은 주어인 '입력 데이터'를 설명하기 위한 앞 서술부가 너무 길어 기억하면서 읽어야 하지만, 두번째 문장은 A는 B다라고 핵심을 말한 뒤 그 이유를 말해줘 단순하고 읽기에 좋다. 그리고 첫 문장의 주어를 가져다가 소제목으로 만들어 자연스럽게 문단을 구성했다. 뒤에 어느 추가 설명이 와도 어떤 내용을 말하는지 방향 잡기가 쉽다.

 

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

먼저 개념을 알아보자.

• 서술식 : '~다'로 끝나는 완전한 문장으로 구성된 글이다무엇을 설명하거나 논증할 때 주로 사용하는 방식이다.  소설이나 신문 기사처럼 개발 가이드 문서는 대부분 서술식으로 쓴다.
• 개조식 : 종결 어미('~다') 대신 명사(완료, 증대 등)나 옹연의 명사형(~했음)으로 끝내는 것을 개조식이라 한다. 주로 릴리스 문서나 장애 보고서를 쓸 때 개조식으로 쓴다.
• 도식 : 사물의 구조나 관계, 상태를 그림이나 서식으로 보여주는 것이다. 이때 가장 간단한 형태의 도식은 표다.

다음과 같은 서술식 설명이 있다고 하자.

OO 메신저에는 4가지 푸시 알림이 있습니다. 공지 알림은 서비스 변경이나 장애, 이벤트 등 메신저 운영사가 직접 보냅니다. 오전 9시부터 오후 6시 사이에만 발송합니다. 메세지 알림은 등록된 친구가 메세지를 보냈을 때 자동으로 시스템이 전송합니다. 친구 등록 알림은 새로운 친구가 등록되었을 때 알려줍니다. 친구 해제 알림은 친구가 탈퇴했을 때 알려줍니다.

이렇게 여러 사항이 유사한 패턴으로 반복될 때는 다음과 같이 개조식으로 쓰는 것이 보기도 좋고 이해하기도 쉽다.

• 공지 알림: 서비스 변경이나 장애, 이벤트 
  •  ⭐︎ 메신저 운영사가 오전 9시부터 오후 6시 사이에 직접 발송
• 메세지 알림: 등록된 친구가 메세지를 보냈을 때 시스템이 자동으로 전송
• 친구 등록 알림 : 새로운 친구가 등록되었을 때
• 친구 해제 알림: 친구가 탈퇴했을 때

그런데 개조식 표현에는 중복과 누락이 있음을 알 수 있다. 메세지 알림, 친구 등록 알림, 친구 해제 알림은 모두 시스템이 자동으로 전송한다(중복). 하지만 친구 등록 알림과 친구 해제 알림을 누가 전송하는지 알 수 없다(누락). 이때 해당 내용을 표로 쓰면 중복과 누락을 막으면서 각 항목의 차이를 더 분명하게 드러낼 수 있다.

알림 종류	상황	발송 방식	발송 시간
공지	서비스 변경, 장애, 이벤트	수동(운영사)	9~18시
메세지	등록된 친구 메세지 발송	자동(시스템)	제한 없음
친구 등록	새로운 친구 등록
친구 해제	친구 탈퇴,

중요한 것은 내용과 형식이 일치해야 한다는 것이다. 줄거리가 있는 설명이나 이야기라면 서술식으로 써야 한다. 여러 가지 종류의 항목과 내용이 반복되거나 서술식에서 강조가 필요한 내용이라면 개조식으로 써야 한다. 각 항목이나 사항의 관계를 명확히 규정하고 싶다면 도식으로 써야 한다.

 

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

글을 개조식으로 쓸 때는 글머리 기호를 꼭 써야 하고, 모두 쓰임새가 달라서 적절하게 사용해야 한다. 쓰임새를 무시하고 아무렇게나 사용하면 말머리 기호의 체계와 의미가 무너져 독자가 이해하기 어렵다.

말머리 기호의 쓰임새는 글의 진술 방식으로 나뉜다. 글의 진술 방식은 설명, 묘사, 논증, 서사의 네 가지가 있다. 진술 방식마다 사용되는 말머리 기호는 다음과 같다.

• 설명: 내용을 구체적으로 설명하거나 나열할 때 ▪︎, ▫︎, ⁃, * 등을 사용한다. 하위 요소로 갈수록 부가 설명이 되면서 중요도가 낮아지므로 크기가 작아지고 들여쓰기를 해야 한다.
• 묘사: 내용을 그림으로 나타날 때 그림 안에 어떤 요소나 영역을 표시하기 위해서는 ①, ②, ③, ⓐ, ⓑ 등의 원형문자를 사용한다.
• 논증: 내용이 논리관계(귀납, 연역, 인과, 유추, 비교, 단계 등)로 구성될 때는 →, ➡, <, >, = 등을 사용한다.
• 서사: 순서나 단계를 나타낼 때는 1,2,3, 가, 나, 다 등 숫자나 문자를 사용한다.

예문을 보면서 자세히 알아보자.

유저를 찾을 수 없어 회원가입에 실패하면, 다음과 같은 순서로 로그를 분석해 원인을 찾을 수 있습니다.
1. 토큰의 수신 여부를 로그로 확인합니다.
  - 정상 수신: "application: didRegisterForRemoteNotificationWithDeviceKoken:"
  - 비정상 수신: "application: didFailToRegisterForRemoteNotificationsWithError:"
2. 해당 앱이 토큰 등록이 되었는지 확인합니다.
  👉 기술 PM에게 문의
3. 해당 앱이 임의 유저의 가입을 허용하는지 확인합니다.
  👉 관리자 시스템 > 가입 관리 화면: 임의 유저 가입 허용 → on