Libx サンプルドキュメント

ドキュメントの編集

ドキュメントを正確で有用かつ最新の状態に保つための効果的な編集と保守方法を学びます。

編集ワークフロー

1. レビューと計画

変更を加える前に：

  • 目標を特定する：何を更新または改善する必要があるか？
  • 現在の状態を確認する：既存のコンテンツを読み通す
  • 変更を計画する：修正、追加、削除する内容を概説
  • 影響を考慮する：変更が関連ドキュメントにどう影響するか？

2. 段階的な変更

  • 小さく始める：一度に一つの論理的変更を行う
  • 頻繁にテスト：変更が期待通りに動作することを確認
  • ローカルプレビュー：開発サーバーを使用して変更を確認
  • リンクをチェック：すべての参照が有効であることを確認

3. レビューと最終化

  • 校正：誤字、文法、明瞭性をチェック
  • 構造の検証：論理的な流れと整理を確認
  • メタデータの更新：フロントマターを適切に変更
  • 徹底的なテスト：すべての例と指示が動作することを確認

一般的な編集タスク

コンテンツの更新

既存のコンテンツを更新する際：

変更前:

## インストール

npmを使用してパッケージをインストールできます：

    npm install @our-package/core

変更後 - より多くのパッケージマネージャーを追加:

## インストール

お好みのパッケージマネージャーを使用してパッケージをインストールできます：

    # npmを使用
    npm install @our-package/core

    # yarnを使用
    yarn add @our-package/core

    # pnpmを使用
    pnpm add @our-package/core

例の改善

例をより包括的にする：

// 変更前：基本的な例
const app = createApp();

// 変更後：エラーハンドリング付きの完全な例
import { createApp } from '@our-package/core';

const app = createApp({
  debug: process.env.NODE_ENV === 'development',
  theme: 'light'
});

app.start().catch(error => {
  console.error('アプリの開始に失敗しました:', error);
});

相互参照の追加

関連コンテンツをリンク：

<!-- 変更前 -->
新しいファイルを追加すると、サイドバーが自動的に更新されます。

<!-- 変更後 -->
新しいファイルを追加すると、サイドバーが自動的に更新されます。
詳しくは[サイドバー自動生成](/ja/v2/components/sidebar-generation)をご覧ください。

フロントマターの更新

このドキュメントシステムでは自動機能により、フロントマターは最小限に保たれています：

---
title: "ドキュメントタイトル"
description: "このドキュメントの簡潔な説明"
---

以下は自動的に処理されます：

  • ナビゲーション：ファイル構造から前/次リンク
  • 順序付け：ファイル名の数字接頭辞から
  • 分類：ディレクトリ構造から
  • 日付：Gitヒストリーから

コンテンツ改善戦略

明瞭性の向上

変更前：

設定でアプリを構成します。

変更後：

`createApp()`にオプションオブジェクトを渡してアプリを構成します：

    const app = createApp({
      debug: true,
      theme: 'dark',
      apiUrl: 'https://api.example.com'
    });

視覚的要素の追加

概念を明確にするための画像、図表、コンポーネントを含める：

変更前：テキストのみ

サイドバーは、カテゴリ別に整理されたすべての利用可能なドキュメントを表示します。

変更後：視覚的補助付き

サイドバーは、カテゴリ別に整理されたすべての利用可能なドキュメントを表示します：

![サイドバーの例](/images/sidebar-screenshot.png)

インタラクティブなナビゲーションについては、[ナビゲーションコンポーネント](/ja/v2/components/navigation)をご覧ください。

文脈の提供

なぜ重要なのかを説明：

変更前：指示のみ

開発時は`debug: true`を設定してください。

変更後：文脈付き

詳細なエラーメッセージとパフォーマンス指標を有効にするため、開発時は`debug: true`を設定します：

    const app = createApp({
      debug: process.env.NODE_ENV === 'development'
    });

これは開発中の問題特定に役立ちますが、パフォーマンスのため本番環境では無効にしてください。

高度な編集技術

MDXコンポーネントの使用

インタラクティブなコンポーネントでドキュメントを強化：

import { Tabs, TabItem, Icon } from '@docs/ui';

## パッケージマネージャーの指示

<Tabs>
  <TabItem label="npm">
    {/* bashコードブロック */}
    npm install @our-package/core
  </TabItem>
  <TabItem label="yarn">
    {/* bashコードブロック */}
    yarn add @our-package/core
  </TabItem>
  <TabItem label="pnpm">
    {/* bashコードブロック */}
    pnpm add @our-package/core
  </TabItem>
</Tabs>

<Icon name="info" /> プロジェクト設定に合ったパッケージマネージャーを選択してください。

コールアウトの作成

重要な情報を強調するためにコンポーネントを使用：

import { Alert } from '@docs/ui';

<Alert type="warning">
  <Icon name="triangle-alert" />
  **重要：** アップグレード前に必ずデータをバックアップしてください。
</Alert>

<Alert type="info">
  <Icon name="info" />
  **ヒント：** 変更をプレビューするには`--dry-run`フラグを使用してください。
</Alert>

コード注釈

コードブロックに説明を追加：

import { createApp } from '@our-package/core';

const app = createApp({
  // 開発用デバッグモードを有効化
  debug: process.env.NODE_ENV === 'development',
  
  // UIテーマを設定
  theme: 'light',
  
  // APIエンドポイントを構成
  apiUrl: process.env.API_URL || 'https://api.example.com'
});

// アプリケーションを開始
await app.start();

品質チェックリスト

編集を最終化する前に確認：

  • 正確性：すべての情報が正しく最新である
  • 完全性：欠けている手順や情報がない
  • 明瞭性：対象読者にとって理解しやすい
  • 一貫性：他のドキュメントのスタイルと用語が一致
  • リンク：すべての内部・外部リンクが機能
  • 例：コード例がテスト済みで機能的
  • メタデータ：フロントマターが適切に更新
  • 構造：論理的な流れと適切な見出し階層

コラボレーションガイドライン

提案の作成

他者の作業を編集する際：

  • 建設的に：明瞭性と正確性の改善に焦点
  • 変更を説明：大幅な修正の根拠を提供
  • 声を保持：元の著者の文体を維持
  • 変更をテスト：編集が何も壊さないことを確認

レビュープロセス

チームドキュメントの場合：

  1. フィーチャーブランチで変更を下書き
  2. ローカルでプレビューしてフォーマットとリンクを確認
  3. 専門家にレビューを依頼
  4. フィードバックに対応し必要な調整を実施
  5. 承認後に変更をマージ

次のステップ

編集のベストプラクティスを理解したら：