몇 백 페이지가 넘어가는 문서를 작성할 때 어떻게 문서를 구조화할 수 있을까요? 이번 포스팅에서는 구글 Technical writing two 과정에서 제공하는 문서 구조화하는 방법에 대해서 공부해보고 제 의견을 덧붙여 보려고 합니다.
문서 유형 구분하기
문서의 유형에 따라 긴 독립형 문서 혹은 상호 연결된 짧은 문서로 구성할 수 있습니다. 일반적으로 제조업에서 제공하는 장비 매뉴얼과 같은 문서는 긴 단일 문서로 구성되어 있습니다. IT업계에서 제공하는 개발 사이트나 위키와 같은 형식으로 구조화된 문서는 상호 연결된 짧은 문서로 구성되어 있습니다.
How-to 가이드, 제품 소개 문서, 개념 가이드는 제품이나 서비스를 처음 접하는 독자를 대상으로 할 때 더 효과적이며 짧고 간략하게 작성해야 더 효과적이라고 합니다. 너무 긴 문서로 작성되면 제품이나 서비스를 처음 접하는 독자는 새로운 용어, 개념을 기억하는데 어려움을 겪을 수 있습니다.
제품이나 서비스에 대해 이미 어느 정도 경험을 가지고 있고 기본 지식이 있는 사람을 대상으로 하는 심층 튜토리얼 문서, User 매뉴얼, API문서 등은 긴 문서로 작성해도 큰 무리가 없습니다.
이때 작성된 긴 문서가 한 번에 읽을 수 있도록 작성되지는 않았습니다. 만약 제가 A 장비 매뉴얼 300페이지를 작성했다고 했을 때 이 장비를 사용하는 사람은 처음부터 끝까지 모든 페이지를 다 읽을 필요는 없습니다. 본인이 원하는 페이지만 찾아서 읽는 경우가 대부분이죠. 이때 목차의 참조 기능을 이용하거나 페이지 검색 기능을 사용하게 됩니다.
문서 정리하기
이 섹션에서는 긴 문서를 작성하기 위한 몇 가지 팁💡을 정리합니다.
개요
개요란 무엇일까요? 네이버에 개요를 검색해보면 '간결하게 추려 쓴 주요 내용'이라고 나옵니다. 글쓰기의 구성 단계에서 각 단락의 중심 내용과 세부 내용을 작성하는데 바탕이 되는 역할을 합니다. 즉, 기술 문서에서 개요는 각 챕터를 시작하기 전에 해당 챕터가 무슨 내용을 포함하고 있는지 요약하고 있는 것이라고 볼 수 있습니다.
개요를 통해 독자는 해당 문서가 무슨 내용인지 대략적으로 파악이 가능이 가능합니다. 또는 문서를 이해하는데 필요한 배경지식을 전달하거나 이 문서의 대상이 누구인지 작성합니다. 실제로 제가 작성한 기술문서를 보겠습니다. (내부 공유문서로 문제가 될 만한 부분을 삭제하고 예시를 들겠습니다.)
위 예시에서는 새로운 챕터를 시작하기 전 개요 섹션을 만들어서 이 장에서는 무엇을 설명하고 있는지 그리고 이 소프트웨어의 목적은 무엇인지 설명하고 있습니다. 목적을 설명함으로써 누구에게 이 소프트웨어가 필요한지, 언제 사용하는지 설명합니다. 만약 시뮬레이터를 처음 사용하는 사용자가 아니라면 굳이 해당 챕터를 읽을 필요는 없기 때문에 원하는 챕터로 이동하여 원하는 내용을 찾을 것입니다.
개요 작성 요령
독자에게 작업을 수행하도록 요청하기 전에 언제/왜 작업을 수행하는지 설명합니다.
📑 제목 아래에 내용 작성하기
아래 예시를 살펴보면 3.3 제목 아래에 해당 챕터에서 소개될 내용을 간략하게 작성했습니다. 순서를 설명하기 전에 이 기능을 언제 사용하면 좋은지 그리고 추가 정보는 어디를 참고하면 좋은지 명시해두었습니다. (파란색 글)
만약 제목 아래에 바로 동작 순서를 설명하면 문서를 읽는 독자는 이 챕터가 무엇을 설명하고 있는 건지 한 번에 파악하기가 힘듭니다. 마찬가지로 제목 1 수준 뒤에 바로 제목 2 수준을 배치하기보다는 위 예시처럼 해당 챕터에서 무슨 내용이 소개될지 작성합니다. 간략한 소개를 작성하면 이 장에서 무슨 내용이 소개되는지 예측할 수 있습니다.
개념을 설명하고 독자가 샘플 프로젝트나 자신의 작업에서 이를 적용할 수 있는 방법을 시연하는 것을 고려합니다. 개념과 함께 적절한 예시를 사용하는 것은 초보 사용자에게 좋은 학습 방법이 될 수 있습니다.
문서를 다 작성하고 난 후 개요를 검토합니다. 처음 작성된 개요와 본문 내용이 일치하지 않을 수 있습니다.
문서 소개 작성하기
독자가 문서에서 찾고 있는 주제와 관련성을 찾지 못하면 해당 문서나 챕터를 건너뛸 가능성이 높습니다. 사용자를 위한 기본 규칙을 설정하려면 다음 정보가 포함된 문서 소개를 제공하는 것이 좋습니다.
문서에서 다루고 있는 내용은 무엇인가요?
독자가 가지고 있어야 할 사전 지식이 있나요?
이 문서에서 다루지 않는 내용은 무엇인가요?
구글에서 제공하는 개요 예시를 살펴보겠습니다. 이 예시에서도 위 항목들이 포함되어 있는 것을 알 수 있습니다.
이 문서는 Froobus 시스템을 사용하여 Markdown 파일을 게시하는 방법을 설명합니다. Froobus는 Linux 서버에서 실행되고 Markdown 파일을 HTML 페이지로 변환하는 출판 시스템입니다. 이 문서는 Markdown 구문에 익숙한 사람들을 대상으로 합니다. 구문에 대한 자세한 내용은 Markdown 참조를 확인하세요. 또한 Linux 터미널에서 간단한 명령을 실행하는 데 익숙해야 합니다. 이 문서에는 Foobus 게시 시스템 설치 또는 구성에 대한 정보가 포함되어 있지 않습니다. Foobus 설치에 대한 정보는 시작하기를 참조하십시오.
첫 번째 초안을 완료한 후 개요에서 말한 내용이 반영되어있는지 전체 문서를 확인하는 것도 중요합니다. 많은 페이지의 문서를 작성할 때는 본문의 내용이 수정될 확률이 높기 때문입니다.😂
📑 연습해보기
작성된 초안을 F@라는 가상의 프로그래밍 언어에 대한 모범 사례 가이드 분석이라고 가정합니다. 맥락에서 관련이 없다고 생각하는 정보를 제거하고 누락된 정보를 추가하는 연습입니다.
[Before] 이 가이드는 F@ 프로그래밍 언어로 작업하기 위한 모범 사례를 나열합니다. F@는 2011년 오픈 소스 커뮤니티 프로젝트로 개발되었습니다. 이 가이드는 F@ 스타일 가이드를 보완합니다. 이 가이드의 모범 사례 외에도 F@ 명령줄 린터도 설치하고 코드에서 실행해야 합니다. 프로그래밍 언어는 헬스 산업에서 널리 채택됩니다. 모범 사례 목록에 추가할 제안 사항이 있는 경우 F@ 문서 저장소에 문제를 제출하십시오.
[After] 이 가이드는 F@ 프로그래밍 언어로 작업하기 위한 모범 사례를 나열합니다. 이 가이드를 검토하기 전에 신규 F@ 개발자를 위한 입문 튜토리얼을 완료하세요. 이 가이드는 F@스타일 가이드를 보완합니다. 이 가이드의 모범 사례 외에도 F@ 명령줄 린터를 설치하고 사용자의 코드에서 실행해야 합니다. 모범 사례 목록에 추가할 제안 사항이 있는 경우 F@문서 저장소에 문서를 제출하십시오.
위 내용을 바탕으로 이제까지 작성된 기술문서에 개요가 잘 작성되었는지 확인해보면 좋을 것 같습니다. 문서 유형과 타깃 독자가 누군지에 따라 개요를 작성하는 방법에 대해서도 다르겠죠? 저도 제가 작성한 문서에 대해서 검토를 다시 한번 해봐야겠습니다😋
