본문으로 건너뛰기

Organizing large documents

When to write large documents​

정보를 정리하는 방법에는 긴 단일 문서로 작성하거나, 비교적 짧은 문서들을 서로 연결하여 작성하는 방법이 있습니다. 일부 독자들은 긴 문서보다는 다른 형태에 더 긍정적으로 반응하기도 합니다. 아래 두 명의 가상의 독자를 생각해 보세요.

  • Hong은 긴 문서를 어렵게 느낍니다. 그는 자신의 질문에 답해 줄 정보를 찾기 위해 사이트 검색을 사용합니다.
  • Rose는 긴 문서를 어렵지 않게 탐색합니다. 그는 웹 브라우저의 내장 검색 기능을 이용하여 현재 페이지에서 유용한 정보를 찾아냅니다.

그렇다면 작성하려는 문서를 하나로 만들어야 할까요? 아니면 여러 개의 문서로 나누어야 할까요? 아래 가이드라인을 고려하세요.

  • How-to 가이드, 개요, 개념적 가이드는 대상에 익숙하지 않은 독자들을 위해 짧은 문서들로 만드는 것이 좋습니다. 예를 들어, 대상을 처음 접하는 독자들은 수많은 새로운 용어, 개념, 사실을 기억해야 하므로 짧은 문서가 도움이 됩니다. 독자들이 빠르게 주제의 개요를 파악할 수 있도록 구성하는 것이 중요합니다.
  • 자세한 튜토리얼, Best Practice 가이드, CLI 레퍼런스 페이지들은 비교적 긴 문서로 작성하는 것이 적절합니다. 특히 해당 도구나 주제에 익숙한 독자들을 위한 문서는 더욱 그렇습니다.
  • 훌륭한 튜토리얼은 긴 문서에서 일련의 과제를 통해 독자들을 이끌어 갑니다. 하지만 일부 분량이 많은 튜토리얼은 짧게 나누었을 때 더 효과적일 수도 있습니다.
  • 많은 긴 문서들은 독자가 한 번에 모든 내용을 읽을 것을 가정하지 않습니다. 예를 들어, 사용자는 특정 명령어나 플래그에 대한 설명을 검색하기 위해 레퍼런스 페이지를 탐색하는 경우가 많습니다.

Organize a document​

Outline a document​

구조적이고 고수준의 개요를 작성하면 주제를 그룹화하고, 보다 세부적인 설명이 필요한 부분을 결정하는 데 도움이 됩니다. 개요는 글을 작성하기 전에 내용을 정리하는 데 유용합니다.

개요는 문서의 서사 구조로 생각할 수도 있습니다. 개요를 작성하는 표준적인 방법은 없지만, 아래 가이드라인을 참고하면 실용적인 팁이 될 수 있습니다.

  • 독자들에게 과제를 부여하기 전에, 왜 그것이 필요한지 설명하세요. 예를 들어, 아래 항목들은 웹페이지 접근성을 높이기 위한 개요 섹션을 나타냅니다.
    • 웹페이지 접근성을 점검하는 브라우저 플러그인을 소개하고, 독자들이 몇 가지 버그를 수정하기 위해 이를 활용할 수 있도록 설명하세요.
    • 플러그인을 실행하는 단계를 나열하고, 웹페이지 접근성을 점검하는 방법을 안내하세요.
  • 개요의 각 단계를 특정 개념을 설명하는 것이나 특정 과제를 수행하는 것으로 제한하세요.
  • 개요를 구성하여 독자들에게 가장 관련성이 높은 정보를 먼저 제공하세요. 예를 들어, 독자가 기초 정보를 찾고 있을 때 프로젝트의 역사를 개요 섹션에서 설명할 필요는 없습니다. 만약 프로젝트의 역사가 중요하다면 문서의 마지막에 링크로 제공하는 것이 좋습니다.
  • 개념을 설명한 후, 독자가 실제 작업이나 샘플 프로젝트에서 이를 어떻게 적용할 수 있을지 제시하세요. 개념적 정보와 실무적 단계를 번갈아가며 설명하는 방식이 학습에 유용합니다.
  • 초안을 작성하기 전에, 문서의 기여자들과 개요를 공유하세요. 개요는 문서를 검토하고 테스트하는 기여자들과 협업할 때 특히 유용합니다.

Introduce a document​

독자들이 문서의 주제를 제대로 이해하지 못하면, 문서를 무시할 가능성이 높습니다. 이를 방지하기 위해 아래 항목을 포함하는 개요를 제공하세요.

  • 문서에서 다루는 내용
  • 독자가 사전에 알고 있어야 할 배경지식
  • 문서에서 다루지 않는 내용

문서를 유지보수하기 쉽게 하려면, 개요에서 모든 내용을 과도하게 설명하지 않도록 주의하세요.

Add navigation​

독자들에게 명확한 내비게이션을 제공하면 필요한 정보를 쉽게 찾을 수 있습니다.

명확한 내비게이션에는 다음과 같은 요소가 포함됩니다.

  • 개요 및 요약 섹션
  • 명확하고 논리적인 주제의 흐름
  • 주제 이해를 돕는 제목 및 부제목
  • 독자가 현재 위치를 파악할 수 있도록 돕는 목차
  • 관련 자료나 추가 정보를 제공하는 링크
  • 다음에 알아야 할 내용으로 연결되는 링크

Prefer task-based headings​

독자가 수행 중인 작업을 반영하는 제목을 선택하세요. 익숙하지 않은 용어나 도구명을 제목으로 사용하는 것은 피하는 것이 좋습니다. 예를 들어, 새로운 웹사이트를 만드는 문서를 작성한다고 가정해 보겠습니다. 이 과정에서 독자는 Froobus 프레임워크를 초기화해야 하며, 이를 위해 carambola CLI 도구를 실행해야 합니다.

처음에는 아래 제목 중 하나가 적절해 보일 수 있습니다.

  • carambola 명령어 실행하기
  • Froobus 프레임워크 초기화하기

하지만 독자가 이러한 용어나 개념에 익숙하지 않다면, Creating the site와 같은 익숙한 제목이 더 적절할 것입니다.

Provide text under each heading​

대부분의 독자는 제목 아래에 간단한 소개글이 포함되어 있으면 이해하기가 더 쉽습니다. 예를 들어, 아래와 같이 제목 바로 아래에 하위 제목을 두는 것은 피하는 것이 좋습니다.

Creating the site​

Running the carambola command​

대신, 짧은 설명을 추가하여 독자를 안내하는 것이 좋습니다.

Creating the site​

웹사이트를 만들려면 carambola 명령줄 도구를 실행해야 합니다. 이 명령어는 사이트 구성을 돕기 위한 일련의 프롬프트를 제공합니다.

Running the carambola command​

Disclose information progressively​

새로운 개념, 아이디어, 기술을 습득하는 과정은 독자가 자신의 속도에 맞춰 문서를 읽을 수 있을 때 더 효과적입니다. 하지만 단시간에 너무 많은 정보를 접하면 부담을 느낄 수 있습니다. 독자가 필요할 때 필요한 정보를 단계적으로 제공하는 것이 좋습니다. 다음과 같은 방법을 활용할 수 있습니다.

  • 새로운 용어나 개념을 설명할 때, 해당 내용을 필요로 하는 지침 가까이에 배치하세요.
  • 긴 텍스트를 적절히 나누어 가독성을 높이세요. 표, 다이어그램, 목록, 제목 등을 활용하여 내용을 구성하는 것이 좋습니다.
  • 긴 작업 단계를 나누어 독자가 쉽게 따라갈 수 있도록 하세요.
  • 간단한 예제와 지침으로 시작하여 점차 복잡한 개념을 설명해 나가세요.