[TW] 시각 자료를 활용한 기술문서

시작하며

안녕하세요. 카카오엔터프라이즈 테크니컬라이팅 팀의 Crystal(김유리)과 Sandy(차신영)입니다.

저희 테크니컬라이팅 팀에서는 어떻게 하면 기술적인 내용을 보다 쉽게 전달할 수 있을지 많은 고민을 하고 있습니다. 그리고 이렇게 어려운 내용의 기술문서를 작성할 때면 시각 자료를 활용하는 것에서 그 해답을 찾곤 하는데요.

A picture is worth a thousand words.
한 장의 그림은 천 마디 말의 가치가 있다.

위의 속담처럼 독자들이 열 줄의 복잡한 설명 대신 그림 한 장으로 개념이나 기능을 이해할 수 있다면, 이보다 더 효율적인 도구는 없을 것입니다. 기술문서에서 시각 자료는 텍스트의 의미를 보다 명확하게 표현할 수 있기 때문에, 정보 전달과 가독성 측면에서도 긍정적인 영향이 있는데요. 오늘은 테크니컬 라이팅에서의 시각 자료 사용을 주제로 이야기를 해보도록 하겠습니다.

시각 자료가 기술문서에 미치는 영향

Nielsen Norman Group가 수행한 조사에 따르면 사람들은 하나의 웹페이지에서 전체 텍스트 중 약 20%만 읽는다고 합니다. 기술문서 사이트에 이런 경향을 반영해 본다면, 독자들은 페이지를 대략적으로 훑어보기만 하기 때문에, 본인이 원하는 정보가 있음에도 해당 정보를 찾지 못할 가능성이 큽니다. 따라서 테크니컬 라이터로서 기술문서에 정확한 정보를 모두 기술하는 것 외에도 어떻게 하면 독자의 시선을 집중시켜 이 문서를 보다 자세히 읽을 수 있도록 유도할 수 있는지가 중요한 과제가 되었는데요. 이런 측면에서 문서 곳곳에 이미지 또는 테이블 등의 시각 자료를 활용하는 것은 훌륭한 대안이 될 수 있습니다. 웹 기반의 인포그래픽 생성 툴을 제공하고 있는 Venngage가 실시한 조사에 따르면, 시각 자료가 있을 때 독자들은 해당 콘텐츠를 읽고 싶은 욕구가 80% 증가한다고 합니다. 또한, 이미지가 있는 게시물을 보았을 때 180% 더 집중한다고 하는데요. 이 조사는 마케팅 관점의 조사이지만, 시각 자료의 힘은 기술문서에서도 동일하게 적용될 수 있습니다.

하지만 이렇게 시각 자료의 힘을 믿고, 문서 곳곳에 시각 자료를 삽입하는 것은 오히려 문서의 가독성과 집중도를 저하시킬 수 있습니다. 따라서 콘텐츠에 따라 적합한 시각 자료를 선정하여, 텍스트와 균형을 맞춰 시각 자료를 배치하는 노력이 필요합니다. 또한, 이미지, 테이블, 순서도 등의 시각 자료를 생성할 때, 일관된 스타일에 따라 동일한 색상과 톤을 유지하는 것이 바람직한데요. 텍스트의 일관성을 위해 스타일 가이드가 필요한 것처럼, 시각 자료별 스타일 가이드를 구성하여 일관된 스타일을 준수하는 것을 제안합니다.

시각 자료의 유형

그렇다면 기술문서에는 어떤 시각 자료를 활용할 수 있을까요? 시각 자료에는 이미지, 도표, 사진, 삽화, 원형 차트, 막대 차트, 선 그래프, 순서도 등이 존재하는데요. 오늘은 그중에서도 기술문서에서 많이 활용할 수 있는 이미지, 테이블, 순서도, 동영상에 대해 자세히 살펴보겠습니다.

① 이미지

이미지는 다이어그램, 화면 캡처, 순서도, GIF 이미지 등의 시각 자료를 의미합니다. 기술문서에 이미지를 사용하면, 독자가 복잡한 내용을 한눈에 파악할 수 있습니다.

기술문서의 시작하기 또는 개요 페이지에서는 해당 서비스의 개념과 기능, API 흐름, 시스템 아키텍처 등을 설명하는데요. 만약 이런 내용을 설명할 때 텍스트로만 기술한다면 독자 입장에서는 자칫 그냥 흘려 넘겨버리는 문서가 될 가능성이 있습니다. 시작하기/개요 페이지는 문서 구성상 서론에 해당하므로, 많은 독자들은 제대로 읽지 않고 성급히 본론으로 넘어가려는 경향이 있습니다. 하지만 시작하기/개요 페이지에는 개발을 시작하기 전에 필요한 개념과 전체적인 설명이 포함되어 있으므로, 전체 문서를 이해하는데 큰 도움이 됩니다. 따라서 테크니컬 라이터 입장에서는 어떻게 하면 독자들이 시작하기나 개요 문서를 읽게 할 수 있을지 많은 고민을 하게 되는데요. 저희는 이런 문제를 해결하기 위해 시작하기/개요 페이지에 텍스트를 뒷받침해주는 이미지를 삽입하고 있습니다. 잘 정돈된 일러스트 이미지는 일단 독자들의 시선을 끌 수 있고, 텍스트를 읽지 않고도 대략적인 내용을 전달할 수 있는 힘이 있습니다. 자연스럽게 독자들은 이미지를 먼저 파악한 후 텍스트를 읽게 되고, 이때 이미 이미지로 한 번 인식한 내용이기 때문에 추상적인 개념 설명을 더 쉽게 이해할 수 있습니다. 이미지는 어려운 개념이나 설명을 보다 가시적으로 만들 수 있다는 점에서 기술문서에서 반드시 필요한 요소라고 할 수 있습니다. 단, 이미지를 삽입할 경우에는 일관된 색상과 톤으로 이미지를 구성하는 것이 좋습니다.

② 테이블

테이블은 행과 열로 구성되어 있으며, 해당 행 또는 열의 내용을 식별할 수 있는 머리글이 포함된 시각 도구입니다. 테이블을 사용해 내용을 요약 및 그룹화하여 보여줄 수 있습니다.

많은 분들이 테이블은 일반적으로 숫자나 수치 데이터에 적합하다고 생각하실 수 있지만, 기술문서에서 테이블은 숫자 데이터 이외에도 다양하게 활용할 수 있습니다. 예를 들어, 기술문서에서 동일한 범주에 속하는 세부 정보를 안내하거나, 스펙 정리, API 목록을 정리할 때에도 테이블을 활용합니다. 이런 정보를 줄 글이나 글머리 기호로도 작성할 수 있지만, 테이블의 머리글이나 열에서 범주를 구분하고 그룹화하면 정보를 효율적으로 전달할 수 있습니다. 따라서 테이블로 변환할 수 있는 텍스트 정보라면, 정보의 범주를 분류하여 테이블로 작성해 보시는 것을 권장합니다. 단, 테이블을 사용할 경우 특정 색상이나 서식 표준을 반드시 따를 필요는 없지만, 문서 안에서는 색상과 스타일을 일관적으로 적용하는 것이 좋습니다.

③ 순서도

순서도란 어떠한 과정을 간단히 기호와 도형으로 도식화한 자료입니다.

기술문서에서는 튜토리얼 가이드나 작업 순서를 설명할 때 순서도를 삽입하는 경우가 많습니다. 기술문서는 문서 계층이나 목차에 따라 복잡한 정보가 톱니바퀴처럼 얽혀있는데요. 독자는 A 작업을 완료 후 수행해야 하는 B 작업에 대해 쉽게 파악할 수 있어야 합니다. 물론 이런 작업 순서는 텍스트로 설명할 수 있지만, 독자의 시선을 집중시키는 데는 순서도가 좋은 도구가 될 수 있습니다. 저희가 관리하고 있는 카카오 i 기술문서에서도 곳곳에 이런 순서도를 많이 활용하고 있는데요. 독자들은 먼저 시각적으로 순서도를 확인하여 전체 프로세스를 이해한 후, 자세한 내용은 텍스트에서 확인하기 때문에 보다 명확한 이해가 가능합니다.

④ 동영상

현대인들이 일상생활에서 동영상을 안 보는 날은 거의 없습니다. 요즘은 동영상으로 거의 모든 정보를 습득하고 있다고 해도 과언이 아닌데요.

이런 측면에서 볼 때 기술문서에서도 동영상은 정보 전달을 위한 좋은 매개체가 될 수 있습니다. 하지만 기술문서의 특성상 보편적으로 모든 문서를 동영상으로 만드는 것은 불가능합니다. 예를 들어, API 레퍼런스 문서는 동영상으로 제작할 필요가 없습니다. 단순한 이미지 자료나 테이블로 충분히 설명이 가능한 내용을 동영상으로 만든다면, 자칫 불필요한 정보가 들어가 문서의 효율성이 떨어질 수 있습니다. 따라서, 동영상을 제작한다면 일단 해당 내용이 동영상으로 제작했을 때 효율적인지 먼저 판단하는 것이 중요합니다. 동영상의 길이는 관련 정보만 포함하여 3-4초로 하되, 더 많은 정보를 전달하고 싶다면 최대 30초까지가 적당합니다. 저희 테크니컬라이팅 팀에서도 동영상 자료를 준비하고 있는데요. 동영상이 기술문서에 가치를 부여하고, 문서의 명확성과 정보 전달을 높일 수 있다는 점을 기억해야겠습니다.

마치며

오늘은 기술문서에 시각 자료가 미치는 영향과 시각 자료의 종류를 살펴보았습니다. API 호출 순서나 시스템 구성처럼 길고 복잡한 내용은 텍스트와 함께 이미지로 구성하고, 범주를 구분하여 내용이나 개념을 분류할 때는 테이블을 사용하면 보다 독자의 이해를 높일 수 있습니다. 또한, 복잡한 절차를 안내할 때는 순서도 같은 차트를 사용하고, 간략한 개념이나 순서를 설명할 때에는 동영상도 좋은 매개체가 될 수 있습니다.

이번 포스팅을 준비하면서, ‘시각 자료가 있을 때 독자들은 해당 문서를 읽고 싶은 욕구를 80% 증가시킨다’는 조사가 흥미로웠습니다. 자칫 어렵고 지겨울 수 있는 기술문서에서 적절한 시각 자료는 눈의 휴식을 줄뿐더러, 정보를 쉽게 파악하게 도와주는 오아시스 같은 존재가 아닐까 생각합니다. 특히, 시각 자료는 독자가 복잡한 개념과 프로세스를 빠르게 이해하는데 도움을 주기 때문에, 문서화 전략의 일부로 기술문서에 다양한 시각 자료를 활용해 보는 것이 좋을 것 같습니다.

아티클 초반에 ‘A picture is worth a thousand words.’라는 속담을 언급했는데요. 그만큼 기술문서에서 시각적 자료의 힘은 우리가 생각하는 것보다 훨씬 더 클 수 있다는 점을 기억해야겠습니다. 감사합니다.