본문
Tech
Technical Writer：効率的な文書管理のための文書エンジニアリング（feat Docusaurus)
관련링크
はじめる前に
伝統的にユーザーガイドは、英語圏ではXML環境で行われ、韓国ではInDesignなどの編集ツールを活用して制作されてきました。
ユーザーガイドをXMLで制作する環境では、DITAというオープンソースでコンテンツをフィルタリングできます。
複数のトピックを一つの目次で構成して、XMLに入力した特定条件従って異なる結果を出力できます。このような理由から、英語圏ではXML環境のテクニカルライティング文化が定着しました。
しかし韓国では、印刷環境を中心に、初期からユーザーガイドはInDesignまたはQuarkXPress、MS-Word環境で制作されてきました。未だ多くのマニュアル会社が、グラフィック編集ツールを利用してマニュアルを制作しています。無論、最近はXML環境に変化する傾向が見られます。
XML環境におけるユーザーガイドは、DITAを使用してコンテンツをフィルタリングします。XMLを使用した文書作成は学習が困難で、他のフォーマットに変換するにはXSLロジックが必要になります。
InDesignなどの編集ツールは、XMLのように文書を再利用できる方法がありません。そのため、同じ内容をコピー・貼り付ける作業が必要で、同じ内容を修正するには、その内容が含まれるすべての文書の修正を繰り返す不便さがありました。
最近は、ユーザーガイドの最終生産物をHTMLフォーマットで作成するための事例が増え、一般化しています。大企業でも、法的に必要な内容中心のみの印刷物として制作され、それ以外の多様かつ膨大な内容のユーザーガイドはHTMLフォーマットで制作したり、制作したHTMLファイルをアプリケーションで作成して配布する傾向にあります。また、IT企業では、自社のソリューション製品に対するユーザーガイド、技術文書を敢えて印刷物として作成せず、SaaS環境の製品増加に伴い、ユーザーガイドをHTMLフォーマットで制作して配布しています。
WhaTapのモニタリングソリューションもその傾向に従って、ユーザーガイドをHTMLフォーマットで制作して配布しています。Markdown形式の文書を作成して、最終成果物はStatic Site Generator（SSG）オープンソースソフトウェアエンジンでHTMLを作成します。SSGのための多くのオープンソースがありますが、WhaTapは現在、Docusaurusを使用しています。React環境に最適化されており、Markdown形式の文書を拡張したMDX文書として使用できます。文書をトピック別に分割して個別に読み込み、再利用できるメリットがあります。
WhaTapのテクニカルライターチームは、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" />
この方法を用いると、複数の商品で同じ内容を再利用できるようになります。
上の画像のように、WhaTapのアプリケーション商品カテゴリに該当するJava、Python、PHP文書は、すべて同じ文書を再利用した成果物です。
しかし、商品によって一部内容が異なる場合がります。次は、Java商品には「ヒープ領域」ウィジェットを提供、PHP商品には「プロセス領域」ウィジェットを提供したケースです。
このように、条件に従って文書の一部の内容が異なる成果物として処理することを、条件付き処理（Conditional processing）といいます。
条件付き処理をする
DITA XMLでは、特定の属性に従って異なる結果を出力するよう調節できます。WhaTapは、この方法論を基にコンポーネントを開発・活用しています。例えば、Java商品には「ヒープ領域」ウィジェットを、PHP商品には「プロセス領域」ウィジェットを提供します。
<!-- Java product --># アプリケーションダッシュボードimport HeapWidget from './_heap-widget.mdx';<HeapWidget />
<!-- _heap-widget.mdx --><InDoc product="java">## ヒープメモリ各サーバーで使用される最大メモリと現在のメモリを表示して、危険レベルに達したサーバーを確認できます。時間に基づくメモリ使用量の変化をリアルタイムで把握できます。メモリラインチャートは、一般的に波打つ状態が続きます。アプリケーションサーバーがリクエスト処理のためにメモリを使用するときに増加します。GC（Garbage Collection）を通じてメモリを整理するときには減少します。ヒープ領域指標には平均値が使用されます。:::tipヒープ領域チャート分析についての詳細は、下記のリンクをご参考にしてください。- [月間WhaTap : モニタリングに注目すべき指標](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">## プロセスメモリ各サーバーで使用できるシステムの最大メモリと指定されたプロセスの使用メモリの合計が表示されます。メモリラインチャートは、一般的に波打つ状態が続きます。アプリケーションサーバーがリクエスト処理のためにメモリを使用するときに増加します。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では、任意で作成したヘッディングに対しては目次を作成せず、Markdownでのみ作成されたタイトルをパーシング（構文解析）して、目次を作成するロジックだけがありました。
この問題を解決するため、タイトル作成のためのコンポーネントを新たに作成し、右側の目次レンダリングのためのコンポーネントも新たに開発して適用しました。
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方法論を適用して、WhaTapの技術文書を効率的に管理する方法についてご紹介しました。これを通じて、テクニカルライターは文書を最小限に作成し、文書に集中して上質な文書を提供することができます。
その他にも、WhaTapの技術文書は、さまざまな文書エンジニアリングを適用しています。不明な点などございましたら、いつでもWhaTapテクニカルライターチームまでお問い合わせください。また、docs.whatap.ioページの画面右下の「フィードバック」ボタンをクリックして、ご意見をお聞かせください。
参照
- DITAは、大規模な文書管理と多様な出力形式への変換を支援して、特に大企業で多く使用されています。XMLをベースに文書の構造的一貫性を保ち、再利用を最大化できるオープンソースです。（RatherBeWriting, DITA-Language）
- Docusaurusは、設定と使用が比較的簡単で、中小規模のプロジェクトやソフトウェアの開発の文書化に適したオープンSSGエンジンです。ReactとMarkdownベースで作成され、ウェブ技術に慣れたユーザーが気軽にアプローチできます。（LogRocket Blog, Docusaurus）