ドキュメント作成の基本

包括的なドキュメントガイドへようこそ！このセクションでは、ドキュメントの作成、編集、管理を効果的に行うために必要なすべてを学びます。

学習できること

この包括的なガイドでは以下を発見できます：

ドキュメント作成: 適切な構造で新しいドキュメントを作成する方法
コンテンツ整理: コンテンツの整理とカテゴリ化のベストプラクティス
コンポーネント使用: ドキュメントを強化するための組み込みUIコンポーネントの使用方法
高度な機能: 自動化、カスタマイズ、デプロイメント戦略

ドキュメント哲学

良いドキュメントは以下のようなものであるべきです：

明確で簡潔: 理解しやすく、従いやすい
よく整理されている: 論理的な構造とナビゲーション
包括的: 必要なトピックをすべてカバー
メンテナンス可能: 更新や最新状態の維持が簡単
アクセス可能: 能力に関係なくすべてのユーザーが利用可能

はじめるためのチェックリスト

ドキュメント作成を始める前に、以下があることを確認してください：

開発環境: Node.js 18+、pnpm、コードエディタ
プロジェクト理解: プロジェクト構造への精通
コンテンツ計画: 何をドキュメント化したいかの明確なアイデア
対象者の理解: ドキュメントを読む人の把握

プロジェクト構造概要

sample-docs は libx モノレポ内の 1 アプリケーションとして管理されています。編集の中心になるディレクトリは次のとおりです。

apps/sample-docs/
├── astro.config.mjs                 # プロジェクト固有の Astro 設定
├── src/
│   ├── config/project.config.json   # バージョン・言語・カテゴリ翻訳
│   ├── content/docs/
│   │   ├── v1/ja/01-guide/...
│   │   └── v2/ja/<category>/<page>.mdx
│   └── env.d.ts など
├── public/sidebar/                  # build:sidebar で生成されるナビゲーションJSON
└── package.json                     # `pnpm --filter=sample-docs ...` で利用

共通パッケージ (packages/ui, packages/content-utils など) はモノレポ直下で管理されるため、アプリ側に独自の src/lib を持たなくても UI/ユーティリティを再利用できます。

よく使うコマンド

pnpm install 後は、ルートで以下を実行して sample-docs だけを動かすのが最速です。

# プロジェクト単体の開発サーバーを起動
pnpm --filter=sample-docs dev

# ドキュメント構造を変更したらサイドバーを再生成
pnpm build:sidebar

# sample-docs だけを選択ビルド
pnpm build:selective --projects=sample-docs

主要機能

自動サイドバー生成

ドキュメントシステムは、コンテンツ構造とフロントマター設定に基づいてサイドバーナビゲーションを自動的に生成します。

多言語サポート

コンテンツは複数の言語で作成でき、自動的な言語切り替えとURL管理が可能です。

コンポーネント統合

@docs/ui パッケージの Icon / Tabs / Alert などを MDX から直接呼び出せます。

バージョン管理

apps/sample-docs/src/config/project.config.json の設定と scripts/create-version.js を組み合わせ、複数バージョンのコンテンツを安全に維持できます。

コンテンツ作成ワークフロー

ドキュメント作成の典型的なワークフローは以下のとおりです：

計画: コンテンツの範囲と構造を定義
作成: MarkdownとMDXを使用して初期コンテンツを作成
強化: コンポーネント、例、対話的要素を追加
整理: 適切なカテゴリとナビゲーションを設定
テスト: リンク、フォーマット、機能を検証
公開: デプロイしてユーザーが利用できるようにする

執筆ガイドライン

ドキュメントを作成する際は：

ユーザーの目標から始める: 何を達成しようとしているのか？
明確な見出しを使用: 論理的な情報階層を作成
例を含める: ただ説明するだけでなく、示す
一貫性を保つ: 全体を通して同じ用語とフォーマットを使用
すべてをテスト: 指示が実際に動作することを確認

次のステップ

ドキュメント作成を始める準備はできましたか？次のガイドでは以下について説明します：

ドキュメントの作成: 新しいドキュメントファイルの作成方法を学ぶ
ドキュメントの編集: 編集プロセスとベストプラクティスをマスター
コンテンツの整理: 最大限の使いやすさを実現するコンテンツ構造
バージョン管理: 複数のバージョンを効果的に処理

あなたのドキュメント作成の旅を始めましょう！