ドキュメントは Alius プラットフォームで最もコンテンツ量の多い部分です。すべてのドキュメントページで一貫した構造を持つことで、ユーザーは情報の整理方法のメンタルモデルを構築でき、検索時間を減らし学習時間を増やすことができます。
統一ドキュメント構造
すべてのドキュメントページは以下の一般的な構造に従うべきで、コンテンツタイプに応じて適宜調整します：
タイトル
- 明確、説明的、具体的
- すべてのドキュメントで文ケースまたはタイトルケースを一貫して使用
- 読者にそのページが何を扱っているかを即座に伝える
ワンラインサマリー
- タイトルの下にページ内容を要約する1文
- 読み込む前に正しいページにいることを確認するのに役立つ
- より大きいまたは強調されたテキストスタイルで表示
対象読者
- そのページが誰向けかを簡潔に記載（初心者、上級者、ハードウェアエンジニアなど）
- コンテンツが自分のレベルに適しているかユーザーが自己判断するのに役立つ
- 小さなタグまたはメタデータ行として表示可能
前提条件
- このガイドに従う前に読者が知っておくべきことやセットアップしておくべきことをリスト
- 適宜前提条件ページにリンク
- 例：「このガイドを読む前に、Agent CLI をインストールし、デバイスを接続しておいてください。」
ステップバイステップの手順
- 順次手順には番号付きステップ
- 各ステップには1つの明確なアクションを含める
- 主要ステップの後に期待される結果を含め、ユーザーが進捗を確認できるようにする
- コマンドライン手順にはコピー機能付きのコードブロックを使用
サンプルコード
- 導入されるすべての概念について動作するコード例を提供
- 疑似コードやプレースホルダー値ではなく、現実的で完全な例を使用
- 複雑な例にはインラインコメントで注釈
- 関連する場合、期待される出力を表示
パラメータ説明
- 設定オプション、API パラメータ、CLI フラグ向け
- 構造化テーブルまたは定義リスト形式で提示
- 含める：パラメータ名、タイプ、デフォルト値、有効範囲、説明
- 必須とオプションのパラメータを明確にマーク
FAQ
- 一般的な質問とエラーを予測
- 質問と回答のリストで提示
- 関連する外部リソースやコミュニティディスカッションにリンク
- 回答は簡潔でアクション可能に
次のステップ
- 現在のガイド完了後に読者が次に何をすべきかを提案
- 関連ドキュメントページにリンク
- 読者の学習パスの継続を支援
関連リソース
- 関連ガイド、API リファレンス、チュートリアル、コミュニティリソースにリンク
- タイプ別にグループ化（ドキュメント、コミュニティ、外部）
- 読者が探していなかったかもしれないコンテンツの発見を支援
ドキュメントフォーマットルール
- 一貫した見出し階層を使用：H1 はタイトル、H2 は主要セクション、H3 はサブセクション
- 重要なノート、警告、ヒントにはコールアウトブロックを使用
- コードブロックにはシンタックスハイライトのために言語を指定
- 構造化データ（パラメータ、比較、互換性）にはテーブルを使用
- 画像と図には説明的なキャプションを付ける
- すべてのリンクは「ここをクリック」ではなく説明的なテキストを使用