개발자를 위한 글쓰기 가이드 - 유영경

테크니컬 라이팅 5단계

1. 계획 세우기: 독자를 명확히 하기
2. 구조 잡기: 계획 단계에서 수집한 정보를 작업 순서에 따라 차례대로 배열
3. 초안 작성: 전달할 정보를 모두 넣는 것에 초점. 내용에만 집중
4. 검토와 재작성: 초안 작성 후 다시 읽어 보며 고치는 단계. 이 단계에 집중 필요
5. 배포: 문서를 배포하는 단계

1단계 계획 세우기

대상 독자 정하기

• 누구를 위해 글을 쓰는지 명확하게 정해야 내용의 깊이 조절 가능
• 대상 독자 정하는 쉬운 방법: 대상의 직무를 확인

설명할 기술의 깊이를 조절하라

• 대상 독자의 직무에 따라 전문 용어에 대한 설명은 달라져야 한다.
• 개발자와 비개발자 모두가 대상인 글을 쓸 때는 각 독자 수준에 맞춰 일단 작성하고 각 직무마다 필요한 추가 설명은 따로 작성한다.

주제를 구체적으로 정하라

• 주제를 구체적으로 좁혀 나가야 한다. 예를 들어, 'GitHub 사용법'이라고 주제를 정하면 GitHub 백과사전을 만들어야 하지만 'GitHub를 사용한 효율적인 문서 검토 방법'으로 주제를 정하면 글의 범위가 명확해진다.

2단계 초안 작성

일단 쓴다

• 흐름도 이상한 것 같고 정확한 내용인지 몰라도 그냥 쓴다.
• 맞춤법 확인도 하지 않는다.

명확성, 간결성, 일관성 3원칙

• 명확성: 개발 업무 관련된 글은 단호하고 명확한 설명과 표현을 사용해야 한다.
• 간결성: 원하는 정보를 빠르게 알리려면 문장을 간결하게 써야 한다.
• 일관성: 문서 전체에서 설명하는 내용이 일관돼야 한다. 같은 의미의 용어나 설명 방법도 일관되게 유지해야 한다.

핵심부터 쓴다

• 제품이나 서비스 가이드와 같이 정보를 전달해야 하는 문서에서는 핵심 내용을 제일 앞에 써야 한다.

역피라미드 방식

• 역피라미드 글쓰기 방식은 결론, 핵심, 주제부터 제시하고 나서 근거나 데이터를 설명하는 방식을 말한다.
• 중요한 내용을 문서 앞부분에서 설명하고 덜 중요한 내용을 차례로 배치하는 것

제목에 요점을 담는다

• 제목 아래 단락의 요점을 압축해 제목으로 쓰면된다.
• 명사로만 제목을 짓는 것은 좋지 않다. (예: 소셜 네트워크 게임 플랫폼 동향 -> 소셜 네트워크 게임 플랫폼을 활용한 게임 제작 동향)

객관적인 근거를 댄다

• 수치 데이터를 제시하면 효과적이다. (예: A 서버보다 B 서버에서 파일을 로딩하는 속도가 훨씬 빨랐다. -> 파일을 로딩할 때 A 서버를 사용하면 1.5초, B 서버를 사용하면 0.9초가 결렸다.)
• 기술 문서에는 추측성 주장이나 입증되지 않은 사실을 적지 않아야 한다.
• 객관적인 수치나 근거를 제시해야 글의 신뢰도가 높아진다.

용어는 일관되게 사용한다

• 같은 어휘를 반복하게 사용하는 것이 지루하고 식상하게 느껴지지 않을까 걱정하지 않아도된다. 테크니컬 라이팅은 정보를 빠른 시간 안에 전달하는 것이 목적이다.
• (보안그룹, 시큐리티 그룹), (인스턴스, instance), (로드밸런서, Load Balancer) 모두 같은 용어이다. 하나로만 통일해서 사용하라
• 설명 방법도 일관성을 유지하라. '화면에서 앱을 선택하라', '화면에서 앱을 터치하라', '화면에서 앱을 탭하라' 모두 같은 의미이다. 정답은 없으니 일관되게만 작성하라

쉽게 쓴다

• 문서라고 해서, 형식적으로 써야 한다고 해서 평소에 잘 쓰지 않는 단어를 쓰거나 문장을 길게 해야 하는 것이 아니다.
• 옆 사람에게 말하듯이 써봐라 (예: '화면 상단 우측 위에 위치한 X 버튼을 클릭하면 창이 닫히는 것을 확인할 수 있다.' -> '화면 오륵쪽 위에 있는 X 버튼을 클릭하면 창이 닫힌다.')

3단계 시각화 요소로 가독성 높이기

목록을 사용해 정리한다

• 점 목록: 문장 안의 여러 항목을 순서 상관없이 나열할 때 점 목록을 사용하면 가독성이 좋아진다.
• 점 목록을 사용할 때는 각 항목이 문법적으로 일관성을 가져야 한다.
• 점 목록을 남발하지 않는다: 각 점 목록이 대등한 관계일 때만 사용하라
• 번호 목록: 번호 목록은 순서가 중요할 때 사용한다.

스크린샷으로 이해도 높이기

• 필요한 부분만 잘라서 넣는다: 필요한 부분만 캡처한다. 특히 화면의 텍스트를 참고해야 할 때는 텍스트가 잘 보이게 해야 한다.
• 그림 크기를 일관되게 지정한다
• 입력값을 채우고 캡처한다
• 스크린샷 위에 텍스트를 추가하지 않는다: 텍스트를 추가할 거면 그림 바깥쪽에 따로 빼서 작성한다.

정보를 비교할 때는 표를 활용한다

• 여러 제품의 장단점을 항목별로 비교할 때, 옵션별로 간단한 설명을 작성할 때 표를 사용하면 가독성을 높일 수 있다.

표가 적합하지 않은 경우

• 표에 행이 1개일 때는 표보다 다른 형식을 고려하는 편이 좋다.
• 문장 중간에는 표를 넣지않는다.
• 표 열이 1개일 때는 표보다 목록을 사용한다.

데이터 성격에 맞는 차트를 사용한다

• 선형 차트: 데이터 간 상관관계를 나타낼 때 많이 사용한다.
• 막대형 차트: 데이터 여러 개의 관계를 나타내는 데 주로 사용한다.
• 파이형 차트: 비교하는 항목이 전체 중 어느 정도, 몇 %를 차지하는지 한눈에 파악하고 싶을 때 사용한다.

시각 자료를 쓰기 전에 소개부터 한다

• 이미지와 목록뿐 아니라 표, 차트, 샘플 코드가 나올 때도 어떤 의도로 사용했는지 소개하는 것을 잊지 않아야 한다.
• 시각 자료를 설명하는 캡션을 활용한다. 그림 캡션에는 '그림 + 숫자 번호 + 그림 내용' 순서를 입력하는 것이 좋다. (예: '그림 1 메일 환경 설정')

4단계 검토와 재작성

객관적으로 문서를 검토한다

간단하면서 효과적인 방법은 다음과 같다.

• 소리 내어 읽기
• 시간을 두고 읽기
• 온라인 문서라면 인쇄해서 읽기

은어는 형식적인 표현으로 바꾼다

• '로그를 까다' -> '로그를 확인하다'
• '무거운 프로그램' -> 실행 속도가 느린 프로그램'
• '로직을 태우다' -> '로직을 적용하다'
• '에러를 잡다' -> '오류를 수정하다'
• '창이 뜨면' -> '창이 나타나면'
• '한글이 깨지다' -> '한글이 제대로 나타나지 않다'

대명사는 일반 명사로 바꾼다

'이를 통해'를 쓰지 않는다.
예: 업무 캘린더를 사용하면 ... 또한 이를 통해 프로젝트 진척도도 관리할 수 있습니다. -> 업무 캘린더를 사용하면 ... 업무 캘린더에서 프로젝트 진척도도 관리할 수 있습니다.

고유한 이름은 정확히 쓴다

문서를 쓰다 보면 고유한 이름이 나오는데 이는 정확히 고유한 이름을 쓴다.

• 'MS' -> 'Microsoft'
• 'Win10' -> 'Windows 10'
• '구글' -> 'Google'
• '크롬' -> 'Chrome'
• '리눅스' -> 'Linux'

단정적인 어조로 확신 있게 쓴다

기술 문서는 독자에게 정확한 사실을 전달한다는 믿음을 주어야 한다. 이럴 수도 있고 저럴 수도 있는 내용을 담으면 안 되며, 단정적인 어조를 유지해야 한다.

• 열기를 클릭하면 새 창이 열리게 됩니다. -> 열기를 클릭하면 새 창이 열립니다.
• ~~ 경우에 '결제 복구 기능'을 사용하면 좋을 듯합니다. -> ~~~ 경우에 '결제 복구 기능'을 사용합니다.

글꼬리를 뚜렷하게 쓴다

• '~~~유일한 방법이라고는 말할 수는 없지 않을까 싶다.' -> '유일한 것은 아니다'
• '~~~해결될 것이라 판단되는 바이다.' -> '해결될 것이다.'
• '~크게 세 가지로 갈라 볼 수 있다.' -> '~~~세 가지다.'

주어와 서술어를 일치시킨다

• '이 서비스가 가진 장점은 사용자에게 편리함을 줄 수 있다.' X
• '이 서비스의 장점은 사용자에게 편리함을 주는 것이다.' O

문장을 짧게 줄인다

• 중복되는 단어가 있으면 없앤다.
• 괜히 덧붙인 말은 없앤다. (예: '활성화 작업 과정을 거치지'에서 '작업'이나 '과정'을 빼도 의미가 통한다. -> '활성하 하지 않아도')
• 필요 없는 조사를 없앤다. (예: '제공이 되며' -> '제공되며')

군더더기 표현을 없앤다

발생

인증서 도메인당 월 8만 원의 비용이 발생한다.
인증서 비용은 도메인당 월 8만원 입니다.

필요

서비스 활성화를 진행하기 위해서는 먼저 콘솔 로그인이 필요합니다.
서비스를 활성화하려면 먼저 콘솔에 로그인해야 합니다.

진행

원하는 파일 유형을 선택해 다운로드 진행해 주세요.
원하는 파일 유형을 선택해 다운로드해 주세요.

피동태보다 능동태로 쓴다

• 피동태: 행동의 주체를 문장의 주어로 두고 이에 맞는 서술어를 쓰는 것이 아니라, 사물이나 관념을 주어로 두고 이에 맞게 서술어를 변형시켜 쓰는 것을 말한다.

예시

Python은 귀도 반 로섬에 의해 개발되었습니다.
Pyhon은 귀도 반 로섬이 개발했습니다.

복잡한 번역체를 다듬는다

• '~에 대해': '~에 대해'는 영어에서 '~about'를 번역한 표현이다. '~을(를)로 바꿔 간결하게 쓸 수 있다.
• '~에 의해': '~에 의해'라는 표현 역시 'by'를 사용한 번역체다.
• 그 외 번역체: ('~을 통해' ->
  '으로'), ('가능, 불가능하다' -> '~을 할 수 있다')

'통해'는 명확한 표현으로 바꾼다

'통해'하나로 여러 가지 의미를 대체하면 분명한 문장을 만들기 어렵다.

이번 테스트에서 나타난 문제점 파악을 통해 부족한 기능을 보완하면... -> 이번 테스트에서 나타난 문제점을 파악해 부족한 기능을 보완하면...

네트워크를 통해 전송합니다. -> 네트워크로 전송합니다.

자주 틀린는 문장 부호

큰따옴표("")

• 큰타옴표는 낱말이나 문장을 직접 인용할 때 사용한다.
• 책 제목, 신문 이름을 나타낼 때도 사용한다.

작은따옴표('')

• 문장의 중요한 부분을 강조할 때 사용한다.
• 인용한 말 안에 있는 인용한 말을 나타낼 때 사용한다.

소괄호

• 소괄호는 보충할 내용을 덧붙일 때, 우리말 표기와 원어 표기를 같이 쓸 때 사용한다.
• 주석이나 보충 내용을 덧붙일 때 사용한다.
• 우리말 표기와 원어 표기를 같이 쓸 때 사용한다.