1-9. Documents

Google Technical Writing Course - 1

총체적인 문서 쓰는 법.

이번 파트의 목차는 아래와 같다.

State your document's scope

좋은 문서는 아래처럼 이 글에서 다룰 내용(scope)를 정의하며 시작한다.

This document describes the design of Project Frambus.

더 좋은 문서는 이 글에서 다루지 않을 내용(non-scope)까지 알려준다.

독자가 특정 내용을 다룰 것이라 예상하고 그 내용을 찾기 위해 무의미하게 시간과 정신을 쓰는 일을 방지할 수 있다.

This document does not describe the design for the related technology, Project Froobus.

이렇게 scope와 non-scope를 먼저 기술하는 것은 글을 쓰는 사람에게도 도움이 되는데, 주제에서 벗어나는 것을 잡아주는 길잡이 역할을 하기 때문이다.

Exercise

아래 문단의 문제점은 무엇일까?

This document explains how to use the Frambus API to create, update, and publish Fwidgets. This document does not explain how to use the Frambus API to delete Fwidgets or cover the history of the Linux operating system.

non-scope에서 명시할 내용은 이 글에서 다뤄질 것이라 예상될 법한 내용이어야 한다.

가령 Frambus API를 설명하며 "create, update, publish는 나오지만 delete는 다루지 않는다"는 것은 합당하지만, 그 누구도 여기서 Linux operating system의 역사를 설명할 것이라고는 생각지도 않을 것이다.

State your audience

좋은 문서는 타겟 독자를 명료하게 밝힌다.

This document is aimed at the following audiences:

software engineers

program managers

또한 직업 뿐 아니라, 선수 지식이나 경험에 대해 언급하면 더 좋다.

This document assumes that you understand matrix multiplication and the fundamentals of backpropagation.

해당 문서를 읽기 전 독자에게 미리 사전 정보를 획득하고 올 것을 요청할 수도 있다.

You must read "Project Froobus: A New Hope" prior to reading this document.

Summarize key points at the start

방대한 기술 문서의 첫 페이지에 공을 들여야 한다는 이야기.

그래야 바쁜 기술자들이 2페이지까지 넘어가지 않겠는가.

Compare and contrast

기존재하는 기술이나 개념과 비교/대조하여 작성함으로서 독자의 이해도를 높인다.

Write for your audience

앞서 나왔던 이야기들의 반복이다.

타겟 독자의 니즈를 정의하고, 실제로 그에 맞춰 문서 구조를 짜는 방법에 대해 다루고 있다.

Define your audience's needs

타겟 독자가 누구인지, 그리고 글을 읽는 목적이 무엇인지 확실히 한다.

또한 글을 읽기 전후 타겟 독자의 사전 지식과 얻어갈 내용에 대해 고려한다.

아래는 퀵정렬과 유사한, 새로 발명한 정렬 알고리즘에 대한 글을 쓴다고 가정했을 때 타겟 독자에 대해 정리한 예시이다.

1. 타겟 독자가 누구인가? → 조직의 모든 SW 엔지니어

2. 타겟 독자의 목적은 무엇인가? → 타겟 독자는 더욱 효과적으로 데이터를 분류할 방법을 찾고 있다. 그들은 이 새로운 알고리즘이 얼마나 유용한지 확인하고, 실제 사용 여부를 결정하기 위해 이 글을 읽는다.

3. 타겟 독자의 사전 지식은? → 코딩을 할 수 있고 퀵정렬을 포함한 정렬 알고리즘을 공부했으나, 대부분은 몇 년동안 정렬 알고리즘을 접하지 않았다.

4. 타겟 독자가 문서를 읽은 후 무엇을 알게 되고 할 수 있게 되는가?

- 기존의 퀵정렬과 비교했을 때 새로운 알고리즘의 유사점과 차이점을 이해할 수 있다.

- 기존의 퀵정렬보다 뛰어난 두 종류의 데이터셋을 알 수 있게 된다.

- 본인이 사용하는 프로그래밍 언어로 알고리즘을 구현할 수 있다.

- 알고리즘의 성능이 떨어지는 두 가지 edge cases를 파악할 수 있다.

Organize the document to meet your audience's needs

타겟 독자의 니즈를 파악했다면, 필요한 정보를 가장 효과적으로 얻어갈 수 있도록 구조화한다.

아래 예시처럼 구성할 수 있다.

1. 알고리즘의 개요

- 퀵정렬과의 비교 및 대조 (BigO 비교 포함)

- 퀵정렬에 대한 위키피디아 링크 첨부

- 알고리즘에 가장 적합한 데이터셋

2. 알고리즘 실행하기

- pseudocode를 통한 알고리즘 구현

- 구현 팁 (흔한 실수에 대한 내용 포함)

3. 알고리즘 심층 분석

- Edge cases

- Known unknowns

+) Known unknowns가 무슨 뜻인지 몰라서 별도로 찾아 정리해두었다. 하기 참고:

https://brunch.co.kr/@eebbc6d856334ef/37

출처 : https://developers.google.com/tech-writing/one/documents