관련링크

시작하기 전에

사용자 가이드는 전통적으로 영미권에서는 XML 환경에서 이루어져 왔고, 한국에서는 인디자인과 같은 편집툴을 활용해 제작되어 왔습니다.

사용자 가이드를 XML로 제작하는 환경에서는 DITA라는 오픈소스를 통해 콘텐츠의 필터링이 가능합니다.

여러 개의 토픽을 하나의 목차로 구성하고 XML에 입력한 특정 조건에 따라 출력되는 결과물을 다르게 할 수 있습니다. 이러한 이유로 영미권에서는 XML 환경의 테크니컬 라이팅 문화가 제대로 안착되어 있습니다.

하지만 한국은 인쇄 환경 위주로 초기부터 사용자 가이드는 인디자인 또는 쿽익스프레스, MS-Word 환경에서 제작되어 왔습니다. 여전히 많은 매뉴얼 회사들이 그래픽 편집 툴을 이용해 매뉴얼을 제작하고 있습니다. 물론 최근 들어 XML 환경으로 변화하는 모습들이 있습니다.

XML 환경에서 사용자 가이드는 DITA를 사용하여 콘텐츠를 필터링합니다. XML을 사용한 문서 작성은 학습에 어려움이 있으며, 다른 포맷으로 변환하려면 XSL 로직이 필요합니다.

인디자인과 같은 편집 툴은 XML과 같은 방법으로 문서를 재사용할 수 있는 방법이 없습니다. 그래서 똑같은 내용을 복사 붙여넣기해야하고, 같은 내용을 수정하려면 해당 내용이 포함된 모든 문서를 반복, 수정해야하는 불편함이 있습니다.

최근 들어서는 사용자 가이드의 최종 산출물을 HTML 포맷으로 만들기 위한 사례가 늘어나고 일반화되어 가고 있습니다. 대기업에서도 법적으로 필요한 내용 위주만 인쇄물로 제작하고 그외 다양하고 방대한 내용의 사용자 가이드는 HTML 포맷으로 제작하거나, 제작한 HTML 파일을 애플리케이션으로 만들어 배포하는 추세입니다. 또한 IT 기업에서는 자사의 솔루션 제품들에 대한 사용자 가이드, 기술 문서를 굳이 인쇄물로 만들지 않고, SaaS 환경의 제품들이 늘어남에 따라 사용자 가이드를 HTML 포맷으로 제작해 배포하고 있습니다.

와탭의 모니터링 솔루션도 그러한 추세에 따라 사용자 가이드를 HTML 포맷으로 제작해 배포합니다. 마크다운 형식의 문서를 생성하고, 최종 결과물은 Static Site Generator(SSG) 오픈소스 소프트웨어 엔진을 통해 HTML을 생성합니다. SSG를 위한 많은 오픈 소스들이 있지만 와탭은 현재 Docusaurus를 사용하고 있습니다. React 환경에 최적화되어 있고, 마크다운 형식의 문서를 확장한 MDX 문서를 사용할 수 있습니다. 문서를 토픽별로 분할해 개별로 불러와 재사용할 수 있는 장점이 있습니다.

와탭 테크니컬 라이터 팀에서는 Docusaurus에서 React 컴포넌트를 개발, 활용해 효율적인 문서 제작 및 관리를 해오고 있습니다.

문서 재사용하기

Docusaurus에서는 MDX 파일을 컴포넌트처럼 재사용할 수 있습니다.

<!-- _markdown-partial-example.mdx -->

<span>Hello {props.name}</span>

This is text some content from `_markdown-partial-example.mdx`.

<!-- someOtherDoc.mdx -->

import PartialExample from './_markdown-partial-example.mdx';

<PartialExample name="Sebastien" />

이 방법을 통해 여러 상품에서 같은 내용을 재사용할 수 있습니다.

위 이미지와 같이 와탭의 애플리케이션 상품 카테고리에 해당하는 Java, Python, PHP 문서는 모두 같은 문서를 재사용한 결과물입니다.

하지만 세부 상품에 따라 일부 내용이 달라질 수 있습니다. 다음과 같이 Java 상품에는 ‘힙 메모리’ 위젯을 제공하지만, PHP 상품에서는 ‘프로세스 메모리’ 위젯을 제공하는 경우입니다.

이처럼 문서의 일부 내용을 조건에 따라 출력되는 결과물을 다르게 처리하는 것을 조건부 처리(Conditional processing)라고 합니다.

조건부 처리하기

DITA XML에서는 특정 속성에 따라 출력되는 결과를 다르게 조절할 수 있습니다. 와탭에서는 이러한 방법론을 차용하여 컴포넌트를 개발하고 활용합니다. 예를 들어, Java 상품에는 ‘힙 메모리’ 위젯을, PHP 상품에는 ‘프로세스 메모리’ 위젯을 제공합니다.

<!-- Java product -->

# 애플리케이션 대시보드

import HeapWidget from './_heap-widget.mdx';

<HeapWidget />

<!-- _heap-widget.mdx -->

<InDoc product="java">

## 힙 메모리

![힙 메모리](/img/apm-dashboard-heap-memory.pn)

각 서버당 사용할 수 있는 최대 메모리와 현재 메모리를 표시해 위험 수치에 있는 서버를 확인할 수 있습니다. 시간에 따른 메모리 사용량 변화를 실시간으로 볼 수 있습니다.

메모리 라인 차트는 보통 계속해서 물결칩니다. 애플리케이션 서버가 요청을 처리하기 위해 메모리를 사용할 때 증가합니다. GC(Garbage Collection)를 통해서 메모리를 정리할 경우에는 감소합니다. 힙 메모리 지표는 평균값을 사용해 표기합니다.

:::tip

힙 메모리 차트 분석에 대한 자세한 내용은 다음 링크를 참조하세요.

- [월간 와탭 : 모니터링에 주목해야할 지표](https://www.whatap.io/ko/blog/94/)

- [Java 힙 메모리 차트 분석 : Ch.1 힙차트 관찰하기](https://youtu.be/FcWfVrETWh4)

- [JAVA 힙메모리 차트 분석 : Ch.2 메모리 릭, 그리고 힙덤프 분석](https://youtu.be/t2q5z4HHNfs)

:::

</InDoc>

<InDoc product="php">

## 프로세스 메모리

![프로세스 메모리](/img/apm-dashboard-process-memory.png)

각 서버당 사용할 수 있는 시스템 최대 메모리와 지정된 프로세스의 사용 메모리를 합산하여 표시합니다.

메모리 라인 차트는 보통 계속해서 물결칩니다. 애플리케이션 서버가 요청을 처리하기 위해 메모리를 사용할 때 증가합니다. GC(Garbage Collection)를 통해서 메모리를 정리할 경우에는 감소합니다. 프로세스 메모리 지표는 평균값을 사용해 표기합니다.

</InDoc>

이처럼 InDoc 컴포넌트를 사용하여 상품에 따라 다른 결과물을 출력할 수 있습니다. product 속성에 따라 현재 페이지에 출력되는 결과물을 선택할 수 있습니다. 여기에 pages 속성을 사용하면 문서 페이지에 따라 출력되는 내용이 달라지도록 조절할 수도 있습니다.

반대로 Xclude 컴포넌트를 추가로 만들어 사용하고 있는데, 이 컴포넌트는 일부 상품에서 내용을 제외할 수 있는 컴포넌트입니다. InDoc 컴포넌트 대신 Xclude 컴포넌트를 사용하는 이유는 InDoc 컴포넌트의 product 속성값을 많이 써야할 경우를 피하기 위함입니다.

_sample.mdx 파일을 여러 문서에서 불러와 내용을 제외하기 위해 InDoc 컴포넌트를 사용하려면 다음과 같이 product 속성을 계속 추가해야합니다.

<!-- _sample.mdx -->

<InDoc product="php,python,go,dotnet,mysql,...">

이 내용은 Java 상품에서만 제외합니다.

</InDoc>

하지만 Xclude 컴포넌트를 이용하면 다음과 같이 제외하는 상품 이름 하나만 속성값으로 추가하면 됩니다.

<!-- _sample.mdx -->

<Xclude product="java">

이 내용은 Java 상품에서만 제외합니다.

</Xclude>

이를 통해 똑같은 문서를 여러 개 만들지 않아도 되고, 문서를 재사용함으로써 반복되는 수정 작업을 최소한으로 줄일 수 있었습니다.

문서 레벨 조정하기

Docusaurus에서는 문서 레벨을 조절할 수 있는 자유도가 부족합니다. 이를 해결하기 위해 제목 작성을 위한 컴포넌트와 오른쪽 목차 렌더링을 위한 컴포넌트를 개발했습니다.

InDoc, Xclude 컴포넌트를 사용해 문서를 효율적으로 관리하고 있지만 문서의 제목 레벨을 원하는대로 조절할 수 없는 단점이 있었습니다. xml 환경에서는 map 단위에서 문서를 구조적으로 배치하여 문서 레벨을 조절할 수 있습니다.

<map>
	<title>DITA work at OASIS</title>
	<topicref href="oasis-dita-technical-committees.dita> <!-- headng 1 -->
		<topicref href="dita_technical_committee.dita"/> <!-- headng 2 -->
		<topicref href="dita_adoption_technical_committee.dita/> <!-- headng 2 -->
	</topicref>
<mapref href"oasis-processes.ditamap"/>
...
</map>

재사용하는 문서를 어떤 위치에 추가하느냐에 따라 문서의 제목 레벨을 조절하고 싶지만 Docusaurus에서는 그러한 자유도를 허락하지 않았습니다. 또한 오른쪽 목차 레벨에 원하지 않는 제목이 노출되어 제목과 내용을 분리해야 하는 불편함이 있었습니다.

Docusaurus에서는 임의로 생성한 헤딩에 대해서는 목차를 생성하지 않으며, 오직 마크다운으로만 작성된 제목들을 파싱하고 목차로 생성하는 로직만 있을 뿐이었습니다.

이러한 문제를 해결하기 위해 제목 작성을 위한 컴포넌트를 새로 생성하고 오른쪽 목차 렌더링을 위한 컴포넌트도 새로 개발해 적용했습니다. Title 컴포넌트를 개발해 Docusaurus가 만들어낸 것과 같은 결과물을 만들고 목차는 html에 렌더링된 콘텐츠를 파싱해 생성하도록 로직을 변경했습니다. Docusaurus에서는 swizzle CLI 명령어를 통해 Docusaurus에서 사용하는 컴포넌트를 추출하고 커스터마이징할 수 있습니다.

import할 문서를 아래와 같이 작성합니다.

<!-- file: _heading_contents.mdx -->

<Title hashid="headings" level={props.level}>Test heading {props.level}</Title>

This document for test.

• hashid: 헤딩 내용의 hash id를 입력합니다.

• level: 헤딩 내용의 레벨을 입력합니다. 2~6까지 입력할 수 있습니다.

다른 mdx 문서에서 _heading_contents.mdx 문서를 아래와 같은 방식으로 문서를 호출하면 같은 내용이더라도 다른 헤딩 레벨로 출력할 수 있습니다.

import TestDoc from "./_heading_contents.mdx";

<TestDoc level={2} />

<TestDoc level={3} />

출력된 결과물은 아래와 같습니다.

마치며…

React 환경에서 DITA XML 방법론을 적용하여 와탭의 기술 문서를 효율적으로 관리하는 방법을 소개했습니다. 이를 통해 테크니컬 라이터가 최소한으로 문서를 생산하고, 문서에 집중하여 좋은 품질의 문서를 제공할 수 있습니다.

이외에도 와탭 기술 문서에는 다양한 문서 엔지니어링을 적용하고 있습니다. 궁금한 사항은 언제든지 와탭 테크니컬 라이터 팀에 문의해주시기 바랍니다. 또한 docs.whatap.io 페이지에서 오른쪽 하단에 ‘피드백’ 버튼을 클릭해 의견을 전달할 수도 있습니다.

참조

• DITA는 대규모 문서 관리와 다양한 출력 형식으로의 변환을 지원하며, 특히 대기업에서 많이 사용됩니다. XML을 기반으로 하여 문서의 구조적 일관성을 유지하고, 재사용성을 극대화할 수 있는 오픈소스입니다. (RatherBeWriting, DITA-Language)

• Docusaurus는 설정과 사용이 비교적 간단하며, 중소규모 프로젝트나 소프트웨어 개발 문서화에 적합한 오픈소스 SSG 엔진입니다. React와 Markdown 기반으로 작성되어 웹 기술에 익숙한 사용자들이 쉽게 접근할 수 있습니다. (LogRocket Blog, Docusaurus)