2-3.Organizing large documents

Google Technical Writing Course - 2

방대한 정보들을 응집력 있는 문서나 웹사이트로 구조화하려면 어떻게 해야 할까?

혹은 이미 산발적으로 흩어져있는 문서나 웹사이트를 보다 접근하기 쉽고 유용하게 바꾸려면 어떻게 해야 할까?

아래 목차는 그에 대한 팁이다.

When to write large documents

많은 양의 정보를 정리할 때는 하기 2가지 선택지가 있다.

하나의 긴 문서

서로 연결된 짧은 문서들 (웹사이트, 위키 등)

어떤 선택을 할 지는 독자층이나 문서 유형에 따라 결정하면 된다.

독자 유형의 예시는 아래 가상의 두 유형을 참고.

- Hong : 긴 문서를 읽기 어려워하고, 필요한 답을 찾기 위해 웹사이트 검색(site search)을 이용함.

- Rose: 긴 문서 내 탐색에 익숙하며, 페이지 내 검색 기능(built-in page search feature, Ctrl+F 등)을 이용해 현재 페이지 내에서 필요한 정보를 찾음.

Hong은 검색을 통해서 한 번에 입맛에 맞는 짧고 잘 정리된 페이지를 찾는 사용자고, Rose는 긴 문서라도 부담 없이 읽을 수 있는 사람이다. 즉 독자의 정보 탐색 방식에 따라 문서를 어떻게 정리할지 달라지기에, 작성하는 문서의 예상 독자가 주로 어느 타입일지 고려해보는 것이 중요하다.

아래는 선택을 위한 조금 더 구체적인 가이드라인:

How-to guide (사용설명서), introductory overviews (소개글 또는 개요), conceptual guides (개념 설명서)

→ 해당 주제를 새로 접하는 독자가 타겟일 경우 짧은 문서 형태가 더 낫다.

→ 생소한 용어, 개념, 사실 등을 기억하는데 어려움을 겪을 수 있음.

→ 이러한 문서를 읽는 독자의 목적은 해당 주제에 대해 빠르게 파악하려는 경우가 대부분.

(ex1: How-to guide) Cloud Firestore Quickstart : Firestore 설정하고 테스트하는 단계별 절차 설명.

(ex2: 소개글) What is Kubernetes? : Kubernetes가 무엇인지, 어떤 문제를 해결하는지 소개.

(ex3: 개념 설명서) TensorFlow - Understanding Tensors : Tensor의 개념과, TensorFlow에서 역할과 구조 설명

In-depth tutorials (심화 튜토리얼), best practice guides (모범 사례), command-line reference pages (명령어 참조 페이지)

→ 해당 툴이나 주제에 대해 어느 정도 숙지하고 있는 독자 대상인 경우가 많아 글이 길어도 괜찮다.

Tutorial

→ 하나의 긴 문서로 작성할 경우, Narrative 방식으로 연관된 작업들을 순차적으로 안내할 수 있다.

(ex) 앱 제작 튜토리얼 : 화면 만들기 > 인증 기능 넣기 > 배포 등의 과정을 하나의 흐름으로 연결해 설명.

→ 작은 단위로 나누는 것이 더 도움이 될 때도 있음.

긴 문서는 보통 처음부터 끝까지 읽기보다는, 필요한 정보를 찾기 위한 참조용으로 활용되는 경우가 많음.

Organize a document

긴 호흡의 문서 작성에 필요한 개요 작성과 도입부 초안 작성 방법에 대한 팁.

문서 전체 초안을 완성한 후, 개요와 도입부를 기준으로 검토하면 누락된 내용이 없는지 파악할 수 있다.

Outline a document

문서 개요 작성 시 참고할 수 있는 팁에 대해 이야기한다.

작업을 수행하기 전에 그것을 하는 이유에 대해 설명할 것. 하기 예시는 웹페이지 접근성을 점검하고 개선하는 튜토리얼의 개요 일부분이다.

- 웹페이지 접근성을 점검하는 브라우저 플러그인을 소개한다

→ 독자가 그 점검 결과 리포트를 이용하여 버그를 수정하게 될 것(이유)임을 설명

- 플러그인을 실행하고 웹페이지 접근성을 점검하는 절차를 나열한다. (본격적인 작업 수행 설명)

개요의 각 항목이 하나의 개념 또는 한 단위의 작업을 다루도록 한다.

→ 즉 한 항목에 하나의 주제를 담으라는 뜻.

독자가 가장 필요로 할 법한 핵심 정보만 개요에서 소개할 것.

→ 예를 들어 작업 튜토리얼에서 '프로젝트의 역사'는 부가적인 정보이다. 만약 문서에 포함되는 쪽이 유용하다고 생각되면, 개요에서 다루는 대신 문서 마지막 부분에 참고 링크를 첨부하는 식으로 하자.

독자가 실제로 그들의 작업에 어떻게 적용할 수 있을지를 보여줄 것.

초안 작성 전, 개요를 기여자들에게 먼저 공유하고 피드백을 받을 것.

Exercise

하기 튜토리얼 개요를 수정할 것. 항목들 간 순서를 재배열하거나, 필요/불필요한 항목들을 추가/삭제한다.

## The history of the project

Describes the history of the development of the project.

## Prerequisites

Lists concepts the reader should be familiar with prior to starting, as well as any software or hardware requirements.

## The design of the system

Describes how the system works.

## Audience

Describes who the tutorial is aimed at.

## Setting up the tutorial

Explains how to configure your environment to follow the tutorial.

## Troubleshooting

Explains how to diagnose and solve potential problems that might occur when working through the tutorial.

## Useful terminology

Lists definitions of terms that the reader needs to know to follow the tutorial.

감이 잡히지 않아서 history만 제외하고, 나머지는 순서를 재정렬했다.

하기와 같이 했는데, 모범답안을 빨간색으로 표시했다.

## Audience

Describes who the tutorial is aimed at.

## Prerequisites

Lists concepts the reader should be familiar with prior to starting, as well as any software or hardware requirements.

## Setting up the tutorial

Explains how to configure your environment to follow the tutorial.

## Useful terminology

Lists definitions of terms that the reader needs to know to follow the tutorial.

## The design of the system

Describes how the system works.

## Setting up the tutorial

Explains how to configure your environment to follow the tutorial.

## Troubleshooting

Explains how to diagnose and solve potential problems that might occur when working through the tutorial.

실제 작동 방식이나 Troubleshooting에 대한 부분은 개요에서 제외되었고, 따로 추가한 항목은 없다.

이렇게 구성한 이유에 대해 챗GPT에게 설명해달라고 해보았고, 답변은 아래와 같다.

1. Audience (대상 독자 설명) : 튜토리얼이 누구를 위한 것인지 먼저 명시.

독자가 자신이 대상인지 판단할 수 있도록 가장 먼저 배치 → 관심 유무 결정.

2. Prerequisites (사전 지식 및 요구사항) : 본격적인 시작 전, 준비가 되었는지 체크.

어떤 개념을 알고 있어야 하는지, 설치해야 할 도구는 무엇인지 명시.

독자가 준비 안 된 상태에서 튜토리얼을 시작했다가 중도 포기하지 않도록 도와줌.

즉, 시작 조건을 설명하는 중요한 부분이라 초반에 배치.

3. Setting up the tutorial (튜토리얼 환경 설정) : 실질적인 준비 단계.

환경 설정은 튜토리얼을 실행 가능한 상태로 만드는 과정.

위의 prerequisites가 ‘이론적 준비’라면, 이건 ‘실행을 위한 실무 준비’.

독자가 ‘지금 당장 따라할 수 있게’ 만드는 목적이므로, 자연스럽게 세 번째.

4. Useful terminology (용어 정리) : 튜토리얼 본문을 원활히 따라가기 위한 언어적 기반.

튜토리얼을 읽으면서 헷갈릴 수 있는 용어를 미리 익히게 하는 역할.

본문에서 갑자기 생소한 용어가 나오는 것을 방지.

너무 초반에 나오면 산만하고, 튜토리얼 본격 시작 직전이나 함께 보는 자료로 적합.

[제외 항목]

1. The history of the project (프로젝트의 역사) : 도입부에서 독자에게 당장 필요한 정보가 아님.

대부분의 독자는 튜토리얼을 학습하려는 목적이지 프로젝트 역사를 궁금해하진 않음.

이런 정보는 부록이나 "About" 페이지로 링크해두는 것이 일반적.

2. The design of the system (시스템 설계 설명) : 도입부가 아닌 본문에서 구체적으로 다루는 내용.

도입부에서 구조적 설명까지 포함하면 진입 장벽이 높아짐.

시스템 설계는 실제 개념 적용 단계에서 다루는 것이 자연스러움.

도입부에선 과한 정보로 느껴질 수 있음.

3. Troubleshooting (문제 해결 팁) : 도입부의 흐름과 맞지 않음.

문제가 생겼을 때 참고할 수 있도록 문서 맨 뒤쪽에 위치시키는 것이 일반적.

도입부에 나오면 독자가 지나치게 어렵다는 인상을 받을 수 있음.

정보는 유용하지만, 타이밍상 부적절.

Introduce a document

도입부에서 문서를 소개할 때는 다음 정보를 포함한다.

이 문서에서 다루는 내용.

이 문서를 읽기 위해 필요한 선행 지식.

이 문서에서 다루지 않는 내용.

추후 유지보수를 고려해 도입부에서 너무 많은 내용을 다루지 않도록 한다.

아래는 Froobus라는 가상의 문서 퍼블리싱 플랫폼에 대한 도입부 예시로, 위에서 제시한 원칙을 기반으로 작성되었다.

This document explains(이 문서에서 다루는 내용) how to publish Markdown files using the Froobus system.

Froobus is a publishing system that runs on a Linux server and converts

Markdown files into HTML pages. This document is intended for people who are

familiar with Markdown syntax.(선수 지식) To learn about the syntax, see the Markdown

reference. You also need to be comfortable running simple commands in a

Linux terminal. This document doesn't include (다루지 않는 내용) information about installing or

configuring a Froobus publishing system. For information on installing Froobus,

see Getting started.

Exercise

F@라는 가상의 프로그래밍 언어에 대한 best practices guide 문서의 도입부 수정하기.

This guide lists best practices for working with the F@ programming language. F@ was developed in 2011 as an open source community project. This guide supplements the F@ style guide. In addition to the best practices in this guide, make sure you also install the F@ command-line linter and run it on your code. The programming language is widely adopted in the health industry. If you have suggestions for additions to the list of best practices, file an issue in the F@ documentation repository.

아래처럼 수정해보았다.

This guide lists best practices for working with the F@ programming language. F@ was developed in 2011 as an open source community project. This guide supplements the F@ style guide. In addition to To demonstrate the best practices in this guide, make sure you also install the F@ command-line linter and run it on your code. The programming language is widely adopted in the health industry. If you have suggestions for additions to the list of best practices, file an issue in the F@ documentation repository. This document doesn't cover how to install and configure F@ programming language. For those information, refer to Getting started.

하지만 아래의 모범답안과는 차이가 많이 난다.

This guide lists best practices for working with the F@ programming language. Before you review this guide, complete the introductory tutorial for new F@ developers. This guide supplements the F@ style guide. In addition to the best practices in this guide, make sure you also install the F@ command-line linter and run it on your code. If you have suggestions for additions to the list of best practices, file an issue in the F@ documentation repository.

모범답안을 토대로 내가 얼마나 엉망진창으로 바꿨는지 항목별로 분석해보았다.

1) In addition to~ 이 부분이 best practices를 확인하기 위해 사전에 준비해야 하는 부분이라고 생각해서 나름 좀 더 자연스럽게 한다고 'To demonstrate'로 바꿨는데, 모범답안을 확인하니 그렇지가 않았다.

사실 프로그래밍이나 command-line linter에 대해 잘 몰랐던 탓이다. 린터란 "코드를 자동으로 검사해서 몬법 오류나 스타일 위반 등을 알려주는 자동 점검 도구"라고 한다. 따라서 여기서 "In addition to"라는 표현을 쓴 것은 "이 가이드에서 제시한 모범 사례 외에도 린터를 사용해서 함께 점검하면 좋다"라는 뜻이었던 것으로, 내가 생각한 것처럼 "증명 또는 시연"의 의미가 아니었다. 그러니 "To demonstrate"라고 바꾸는 것도 얼토당토않을 수 밖에.

추가로, 모범 답안에서는 말 그대로 best practices를 보기 전에 '입문 튜토리얼을 먼저 완료하라'라는 보다 명확한 선수지식을 명시했다.

2) '다루지 않는 내용'을 추가했지만, 문법적으로나 글 흐름상으로나 어색한 부분이 많다. 우선 For those information가 아니라 For that information이라는 표현이 맞다. 그리고 린터를 설치하라는 말 다음에 갑자기 '~를 다루지 않는다'고 전환되어 글의 흐름이 깨진다.

3) "If you have suggestions ~" 이 부분은 앞서 제시된 원칙에 포함되지는 않지만, 도입부에서 독자의 참여를 유도하는 부분으로 하기와 같은 목적을 달성할 수 있다. (feat. 챗GPT)

- 커뮤니티 중심 문서라는 메시지 전달 : 독자 = 기여자(contributor)가 될 수 있음.

- 문서의 유연함 강조 : 계속 발전 중인 가이드라는 인상을 줌.

- 오픈소스 문화에 부합 : 오픈소스에서는 문서도 협업 대상이기 때문에 도입부에 참여 방법을 안내하는 것이 흔함.

내부 문서, 교육용 가이드, 공식 튜토리얼 등 독자 참여가 필요 없는 경우에는 이러한 참여 유도가 포함되지 않는 것이 좋다. 하지만 오픈소스, 특히 독자가 이미 해당 주제에 대한 기본적인 배경 지식이 있다는 가정하에 쓰인 best practice guide 에서는 이러한 유도 문장이 도입부에 포함되는 것이 관례인 듯 하다.

결론적으로, 개발 문서에 대해 더 많이 읽고 접해봐야 보다 제대로 된 교정이 가능하다...

Add navigation

독자가 지금 자신이 어느 문서의 어느 위치에 있는지, 앞으로 어디로 가야할지를 쉽게 파악할 수 있도록 적절한 수단을 사용하라는 것. 제목(heading)이나 목차(Table of Contents), 링크 등을 이용할 수 있으며, 하기 요소들은 좋은 navigation의 조건들이다.

도입부와 요약 섹션 : 독자에게 출발점과 종점을 알려주는 역할을 한다. 도입부를 통해 이 문서의 방향을 파악할 수 있고, 요약 부분에서 자신이 무엇을 얻었고 추가로 얻어야 하는 것이 있는지 돌아볼 수 있다.

논리적 전개 : 독자가 다음에 어떤 내용이 나올지 유추함으로서 문서 안에서 방향성을 잃지 않게 한다.

주제에 맞는 제목과 부제목

현재 위치를 파악할 수 있는 목차

관련 자료 또는 심화 정보로 연결되는 링크

다음에 다룰 내용으로 연결되는 링크

Prefer task-based headings

실제 작업해야 하는 내용이 담긴 제목을 사용할 것. 그리고 제목에 독자가 익숙하지 않을 수 있는 용어나 툴은 가급적 삼갈 것.

예를 들어 새로운 웹사이트를 만드는 과정에 대해 문서 작업을 한다고 가정하자. 웹사이트를 만들기 위해서는 Froobus 프레임워크를 초기화해야 하고, 초기화를 위해서는 carambola라는 커맨드라인 도구를 실행해야 한다. 따라서 작업 베이로 제목을 짓는다고 했을 때, 아래와 같은 제목은 얼핏 타당해 보인다.

Running the carambola command

Initializing the Froobus framework

그러나 carambola나 Froobus라는 용어 자체가 익숙하지 않을 수 있기에, 이보다는 "Creating the site" 같은 보다 직관적인 제목을 사용하는 것이 낫다.

Provide text under each heading

독자의 이해를 돕기 위해 제목 아래에 간단한 설명을 덧붙일 것.

다만 상위 제목 아래 바로 하위 제목이 오는 구조는 피하도록 하자.

## Creating the site

### Running the carambola command

2단계 제목 아래 바로 3단계 제목이 오는 예시 - 두 제목 사이에 간단한 설명이 오는 것이 좋다.

아래 예시처럼 보완할 수 있다.

## Creating the site

To create the site, you run the `carambola` command-line tool. The command

displays a series of prompts to help you configure the site.

### Running the carambola command

Exercise

각 항목의 순서를 바꾸거나, 새로운 항목을 추가하거나, 불필요한 항목을 삭제하는 등의 방법을 통해 아래 개요를 개선하기. 하위 항목(secondary entries)을 추가해도 좋다.

About this tutorial

Advanced topics

Build the asset navigation tree

Define resource paths

Defining and building projects

Launch the development environment

Defining and building resources

What's next

Define image resources

Audience

See also

Build an image resource

Define an image project

Build an image project

Setting up the tutorial

Select the tutorial asset root

About this guide

이 문제는 사실 풀기가 조금 어려웠는데

각 소제목들을 어떻게 나눠야할지 감이 잘 잡히지 않아서.

즉 "Build the asset navigation tree" 등 용어가 낯선 등, 개발 쪽 배경 지식이 없었기 때문이다.

반대로 말하면 이 매뉴얼은 비개발자, 혹은 프로그래밍 입문자가 읽을 만한 문서는 아닌 것 같다.

어쨌든, 그런 이유로 바로 모범 답안을 참고했다.

삭제한 항목은 없고, 파란색 항목이 추가되었다.

2단계 제목과 그에 맞는 하위 제목을 논리적으로 구성하는데 초점을 맞췄다.

## About this tutorial

### Audience

### About this guide

### Advanced topics

## Setting up the tutorial

### Select the tutorial asset root

### Launch the development environment

### Build the asset navigation tree

### Define resource paths

## Defining and building resources

### Define an image project

### Build an image project

## Defining and building databases

### Define a database

### Build a database

## Pushing, publishing, and viewing a database

### Push a database

### Publish a database

### View a database

## Configuring display rules for point data

### Define, configure, and build vector data

## See also

### Sample data files

## What's next

이해가 되지 않는 부분들을 조금 더 찾아보고 이렇게 구성한 이유를 정리해보았다. (feat.챗GPT)

그리고 살도 조금 더 붙여보았다.

## About this tutorial → 이 튜토리얼이 무엇을 위한 것인지 설명 (튜토리얼 자체에 대한 소개).

(ex) 이 튜토리얼은 사이트를 만드는 방법을 소개한다. ~~를 배우게 될 것이고, ~~ 순서로 진행된다.

### About this guide → "About this tutorial"과 다르게 문서시스템의 구성, 스타일, 규칙 등을 소개.

(ex) 이 가이드는 Froobus 프로젝트 문서의 일부로, 스타일은 ~~고, 모든 구성은 ~~ 구조를 따른다.

### Advanced topics → 보통 맨 뒤나 "What's next" 앞쪽에 나오지만, 여기서는 도입부에 나와 독자가 학습 깊이를 미리 파악할 수 있게 함. (이러한 심화 내용이 있다는 예고편 정도로 이해하면 됨.)

## Setting up the tutorial → 튜토리얼 준비 단계. 환경설정 등이 포함.

### Select the tutorial asset root → 프로젝트 디렉토리 설정.

** Asset root : 웹 개발에서 사용되는 용어로, 정적 자산(이미지, CSS, JS 등)의 기본 디렉토리, 즉 최상위 경로를 나타냄.

### Launch the development environment → 작업 공간 실행

(ex) VSC 설치 등.

### Build the asset navigation tree → 프로젝트 리소스를 트리 구조로 구성.

(ex) 왼쪽 탐색 창에 보이는 폴더 트리 구조 설계.

### Define resource paths → 시스템이 리소스를 참조할 수 있도록 실제 경로 등록(JSON 설정 파일 등).

(ex) { "map_icon": "/assets/images/map_icon.png", "city_data": "/assets/data/cities.csv" }

→ 시스템에 "지도 아이콘은 /assets/images/map_icon.png에 있다"고 알려줌.

## Defining and building resources → 실제로 작업하는 과정으로, resource (콘텐츠)을 만드는 단계.

** resources : 실질적인 콘텐츠 (이미지 파일, JSON이나 CSV 등의 데이터 파일, 글꼴, UI 구성 요소 등)

** 여기서 resources는 "image project" → 이미지 중심의 콘텐츠를 제작하고 실질적인 결과물 생성.

### Define an image project → 리소스 만들기 위한 속성, 이름, 구조 등 지정

(ex) 이 프로젝트는 '이미지 묶음 A'로 이름 짓고, PNG만 포함하고, 3개 이미지가 들어간다.

### Build an image project → 정의한 내용을 바탕으로 실제로 실행 가능한 형태로 변환

(ex) 이미지들을 묶어서 시스템에서 쓸 수 있는 .imgproj 같은 파일로 패키징

## Pushing, publishing, and viewing a database → 앞서 만든 DB를 외부로 내보내고 확인. 배포 과정.

** 기존에는 DB를 만드는 과정은 있었지만, 실제로 사용하고 검토하는 과정이 없었음.

⇒ DB는 배포 과정이 더 중요하기 때문에, DB에 대한 가이드라면 반드시 배포 과정에 대한 내용 포함.

### Push a database → 로컬에서 만든 DB를 서버나 외부 저장소로 업로드.

### Publish a database → 업로드한 DB를 다른 사람이 볼 수 있게 공개 설정.

### View a database → 업로드한 DB가 실제로 어떻게 보여지는지 확인.

## Configuring display rules for point data → 도입부에서 나온 "Advanced topics"에 해당.

** 기존에는 "고급 내용"에 대한 내용이 빠져있음. 도입부에서 예고했기 때문에, 이 내용도 추가 필요.

### Define, configure, and build vector data → ‘포인트 데이터’를 설정하는 고급 기능

(ex) 지도에 찍히는 좌표나 위치 정보 설정 (서울은 파란 점, 부산은 빨간 점으로 보이게 하는 등).

Disclose information progressively

정보를 너무 한꺼번에 공개하지 말고, 필요한 시점에 하나씩 전달하라는 내용.

아래 팁을 참고한다.

새로운 용어나 개념은 실제로 사용되는 부분 근처에서 소개.

긴 텍스트 블록은 나눠서 사용하고, 한 페이지에 문단이 너무 많이 들어가지 않게 표, 다이어그램, 리스트, 소제목 등을 활용해 가독성을 높일 것.

작업 step이 많아서 리스트가 길어질 경우, sub-task로 나눠서 짧은 리스트로 구성.

간단한 instruction 및 예시로 시작해서 심화 과정은 차차 추가할 것. 예를 들어 폼(form)을 만드는 튜토리얼이라면 먼저 텍스트 입력을 다루는 기본적인 방법을 소개한 후, 객관식/이미지 응답/기타 입력 방식 등에 대해 단계적으로 추가.

* 출처 : https://developers.google.com/tech-writing/two/large-docs#introduce_a_document