VuePress：ドキュメントを簡単に

ユーザーとの対話を必要とするプロジェクト（エンドユーザー、メンテナーなど）に関しては、成功と失敗の違いを生む重要な要素が1つあります。それは、優れたドキュメントです。 これは、プロジェクトの規模に関係なく当てはまります。 結局のところ、プロジェクトに1対1のサポートを提供することを除けば、ドキュメントは問題を解決しようとしているユーザーにとっての最初の防衛線です。 そして、あなたがそれを好むかどうかにかかわらず、不十分なドキュメントのために彼らの問題を解決することができなかった後にあきらめるユーザーから決して聞くことはありません。

優れたドキュメントを作成する際の課題

優れたドキュメントを作成する場合、チームが頻繁に遭遇する4つの問題が繰り返し発生します。

1. 多くの場合、ドキュメントは古くなっています。
   プロジェクトのドキュメントがないことは苛立たしい経験になる可能性がありますが、古いドキュメントがあることは間違いなく悪いことです。 結局のところ、ドキュメントを作成する目的は、ユーザーが信頼できる公式の知識体系をユーザーに提供することです。 古くなると、ユーザーは時間を無駄にし、最終的には製品への信頼を失います。
   
   ドキュメントが古くなる主な理由は、ドキュメントのメンテナンスがコードの変更とは別であるためです。 多大な時間とエネルギーを投資しないと、これを解決するのは難しい場合があります。理由は次のとおりです。
   
   1. ドキュメントは通常、ConfluenceやWikiなどのサードパーティサービスに存在します。
   2. 開発者は通常、ドキュメントよりもコードの記述に関心があります。
2. ユーザーは簡単にフィードバックを提供することはできません。
   ドキュメントがどれほど優れていると思っても、フィードバックを提供できる実際のユーザーでテストしなければ、最終的には意味がありません。 前述のように、ドキュメントなどの有効性を評価する際の一般的なバイアスは、問題を解決できずに諦めたユーザーを考慮に入れていないことです。 ユーザーが製品をどのように使用するかについてのすべてのシナリオを説明できるチームはないため、ユーザーはフィードバックを提供するための簡単で信頼できる方法を持っている必要があります。
3. ドキュメントは、多くの場合、パワーユーザーがパワーユーザーのために作成します。
   ウィキやREADMEファイルなどの標準ツールを使用する場合の欠点は、ライブラリやテクノロジースタックに関する既存の知識を持っていることが多い特定のユーザーセットにしか対応できないことです。 その結果、彼らがスペースをナビゲートして必要なものを見つけるのはかなり簡単です。 ただし、新しいユーザーはこの事前知識が不足しているため、多くの場合、ユーザーを引き付けるためにはるかに没入型のエクスペリエンスが必要になります。
   
   この例は次のとおりです。
   
   • うまく設計されたウェブサイト、
   • 検索機能、
   • ガイド付きサイドナビゲーション、
   • 簡単に識別できるメタ情報（つまり、最終更新日）、
   • 簡単に理解するのが難しいテキストの壁を越えて広がる没入型コンテンツ。
4. ドキュメントの保守を困難にする貧弱なインフラストラクチャ。
   ユーザーが理解できる優れたドキュメントを作成することはそれほど難しくないかのように、開発者がドキュメントを作成および/または維持できることは、その長期的な実行可能性にとって非常に重要です。 したがって、開発者がドキュメントを作成および/または維持するために対処しなければならない追加の障壁ごとに、最終的に失敗する可能性が高くなります。 結果として、ドキュメントの作成経験と保守が可能な限りシームレスで魅力的であることが重要です。

これらすべてのことを私たちのために行うことができるツールがあれば…

VuePressを入力してください

VuePressを最初に聞いたとき、それはVue.jsとWordPressの融合であると推測したくなるかもしれません。 代わりに、VuePressを次のように考える必要があります。

Vue.js +印刷機

なぜなら、すべてが言われ終わったら、VuePressは静的サイトジェネレーターだからです！

皆さんの中には、「待ってください。 別の静的サイトジェネレーター？ 大したことは何ですか？」

静的サイトジェネレーターであるツールは多数ありますが、VuePressは、単一の理由でパックの中で際立っています。その主な目的は、開発者がプロ​​ジェクトの優れたドキュメントを簡単に作成および維持できるようにすることです。

VuePressがドキュメントの作成に非常に強力なのはなぜですか？

答えは簡単です。 これは、開発者が楽しいオーサリングエクスペリエンスを維持しながら、優れたドキュメントサイトを作成できるようにするという1つの目標を念頭に置いて設計されました。 これは、開発者が次のことを行うためのフレームワークを提供することを意味します。

• 美しいドキュメントサイトを作成し、
• すべてのドキュメントサイトに不可欠なビルド済みの機能が付属しています。
• オーサリングエクスペリエンスを最適化して、Markdownファイルを更新するのと同じくらい簡単にします。

VuePressは既存のコードベースと共存できます

これが、私が強くお勧めする主な理由の1つです。 ドキュメントの保守に関しては、ドキュメントが古くなることを保証する1つの方法は、開発者がコードを作成するときにドキュメントを更新するのを困難にすることです。 開発者に2つの異なる場所での更新を強制することによってオーサリングエクスペリエンスを困難にすると、多くの摩擦が発生し、多くの場合、ドキュメントが道端に残されてしまいます。 これは、開発者がコードベース自体に加えて、wikiなどのサードパーティツールを維持する必要がある場合によく見られます。

これは静的サイトジェネレーターであるため、コードとまったく同じリポジトリに存在できることを意味します。

このサンプルWebアプリ構造でわかるように、コードは通常どおりsrcディレクトリにありますが、すべてのドキュメントを含むdocsディレクトリがあります。 これは、次の利点が得られることを意味します。

• すべてのドキュメントはバージョン管理されています。
• プルリクエストには、ドキュメントとコードの変更の両方を含めることができるようになりました。
• コードとドキュメントのローカルインスタンスを同時に実行するための個別のスクリプトを作成します。
• ビルドパイプラインを利用して、新しいドキュメントサイトの展開がコードの展開と同期しているかどうかを判断します。

デフォルトのテーマには標準構成が付属しています

ドキュメントを作成するのはそれなりに難しいので、VuePressは通常行う必要のある多くの決定をオフロードし、オーサリングエクスペリエンスを容易にするための多数の組み込みのデフォルトを備えています。

• コンテンツの書き込みは、主にMarkdownを使用して行われます。
  これは、Markdown構文に関する既存の知識を活用して、テキストのスタイルとフォーマットを設定できることを意味します。

• コード構文の強調表示。
  すべて自分でサイトを構築している場合は、カラー構文の強調表示ライブラリに取り組む必要があります。 しかし、VuePressでコードブロックを追加できるので幸運です。すべてがゼロ構成で準備ができているので、とても簡単です。

• ページレベルのメタデータを定義するための最前線。
  Markdownファイルでオーサリングしている場合でも、フロントマター（YAML、JSON、TOMLなど）を使用してページのメタデータを定義し、コンテンツの管理をさらに簡単にすることができます。

 --- title: Document Like a Pro lang: en-US description: Advice for best practices tags: - documentation - best practices ---

• カスタムマークダウンコンテナ。
  ご存じない方のために説明すると、Markdownには、カスタムコンテナなどの美しいUIコンポーネントを作成するためのさらに便利なショートカットを追加する拡張機能があります。 また、ドキュメントで非常に役立つため、VuePressはすでに構成されているため、箱から出してすぐに使用できます。

組み込みの検索機能

それに直面しよう。 すばらしいドキュメントを書くのにどれだけの時間を費やしても、ユーザーがそれを見つけられなければ、最終的には役に立たなくなります。 これには一般的に2つのアプローチがあります。

1. いつの日かユーザーがサイトの適切なページを見つけられるようになることを期待して、検索エンジンロボットがサイトをゆっくりとクロールするのを待ちます。 素晴らしい解決策ではありません。
2. 独自の検索機能を構築しますが、検索インデックスを作成して検索を実行するサーバー側のコードが実行されていないため、静的サイトに実装するのは難しい場合があります。 言うまでもなく、これは製品自体から開発時間を奪っています。 ですから、これも素晴らしいことではありません。

私たちにとって幸運なことに、VuePressはその日をもう一度救うためにここにいます！

VuePressには、独自の「検索エンジン」を生成する検索機能が組み込まれています。 追加のデータベース設定や構成なしで、VuePressはドキュメント全体をスクレイプして、すべてのh1とh2をユーザーに表示する単純な検索エンジンを生成するように設定されています。

さて、あなた方の何人かは考えているかもしれません、

「検索用の低レベルのインデックスを提供するものが必要な場合はどうなりますか？」

VuePressは、要件を満たしている場合にその機能を無料で提供できるAlgolia DocSearchと簡単に統合できるように設計されているため、ここでもカバーされています。

サイドバーのナビゲーションは、機能のオンとオフを切り替えるのと同じくらい簡単です

コンテンツの管理を担当したことがある人なら誰でも、アイテムをネストしたサイドバーを作成し、下にスクロールしながらリーダーがどの位置にあるかを追跡することがどれほど複雑になるかを知っています。 では、より良いドキュメントを書くことができるのに、なぜそれに時間を費やすのでしょうか。 VuePressを使用すると、サイドバーはページの前書きを切り替えるのと同じくらい簡単です。

見過ごされがちな重要なメタデータの自動生成

ユーザーが遭遇する可能性のある最も苛立たしいことの1つは、古いドキュメントです。 ユーザーが手順を実行し、何かが機能しない理由を理解するのに苦労している場合、最終更新日を簡単に見つけることができると、プロジェクトのユーザーとメンテナーの両方にとって非常に役立ちます。

シンプルな設定で、VuePressはページに最終更新日を自動的に出力できるため、ユーザーは常に最終更新日を知ることができます。

さらに、VuePressを少し構成するだけで、すべてのページの下部にリンクを自動的に生成して、ユーザーがドキュメントへのプルリクエストを簡単に作成できるようにすることで、ユーザーがドキュメントに投稿するのが非常に簡単になります。

それはあなたのユーザーにとってそれよりもはるかに簡単になることはありません。

静的ホスティングサイトへの展開

VuePressはそのコアで静的サイトジェネレーターであるため、これは、次のような一般的なホスティングプラットフォームにデプロイできることを意味します。

• Netlify
• GitHub Pages
• GitLabページ
• Heroku
• 今

サイトを構築するために必要なのは、ディレクトリが存在する場所でvuepress build {{ docsDir }}を実行することだけであり、Web上にライブで展開するために必要なすべてのものが揃っています。

注：これを行う方法の詳細なガイドについては、VuePressの公式導入ガイドを確認してください。

マークダウンファイル内のVueの活用

分かってる。 MarkdownでVue.jsを使用できますか？！ はい、あなたはその権利を読んでいます！ 技術的にはオプションですが、これはおそらくVuePressの最もエキサイティングな側面の1つです。これにより、これまで不可能だったようにMarkdownコンテンツを強化できるからです。

反復データを1つの場所で定義し、補間を使用してどこでも更新できるようにします

以下の例では、ローカル変数（フロントマターで定義されている変数など）とグローバル定義変数（サイトタイトルなど）を活用する方法の簡単な例を示しています。

 --- title: My Page Title author: Ben Hong --- # {{ $page.title }} Welcome to {{ $site.title }}! My name is {{ $page.author }} and I'll be your guide for today!

Markdown内でVueコンポーネントを使用する

これを読んだ後、少し時間を取ってみましょう。ただし、必要に応じて、完全なVueインスタンスを備えたライブVueコンポーネントを使用することもできます。 構成にはもう少し作業が必要ですが、ドキュメントで実行されるカスタムコンテンツを作成しているため、これは予想されることです。

これは、MarkdownファイルでCounterコンポーネントがどのように見えるかの簡単な例です。

これは、ドキュメントで利用できるカスタマイズの最も強力な部分です。これは、カスタムコンテンツを作成する自由が、標準のMarkdownの機能をはるかに超えていることを意味します。 したがって、デモを提供する場合でも、インタラクティブなコードを提供する場合でも、アイデアは無限です。

次のステップ

ユーザーが製品の使用方法を学ぶための美しいドキュメントサイトを設定したい場合、VuePressほど簡単にはなりません。 また、VuePressはVue.jsを使用するプロジェクトでのみ使用する必要があると考えるのは簡単かもしれませんが、これは真実から遠く離れることはできません。 ドキュメントサイトにVuePressを活用するさまざまなタイプのプロジェクトの例を次に示します。

• クラフトCMS
• UmiJS（React用に構築されています）
• openHAB
• 孔雀

結局のところ、VuePressを使用しているかどうかに関係なく、これがユーザーにとってより良いドキュメントを作成するためのインスピレーションになったことを願っています。

その他のリソース

この記事では取り上げなかったすばらしいことがたくさんあります（テーマ、ブログなど）が、詳細を知りたい場合は、次のリソースを確認してください。

• 公式VuePressドキュメント
• VuePress関連リソースの厳選されたリスト
• VuePressギャラリー
• VuePressブログボイラープレート