ドキュメンテーションの構成¶
プロジェクトの構成¶
ドキュメンテーションのプロジェクトを <root>/docs に配置する。
コンポーネント¶
ソースディレクトリ以下にコンポーネントごとにディレクトリを作成し、関連するドキュメントを配置する。
| パス | コンポーネント | 内容 |
|---|---|---|
./ |
フレームワーク | インデックスやリリースノート、サイトマップ等 |
intruduction/ |
フレームワークの紹介 | フレームワークの概要説明、入門ドキュメント、開発の流れ |
application/ |
アプリケーション開発環境の整備 | 開発環境構築手順やバッチアプリケーションのビルド手順等 |
dmdl/ |
Asakusa Data Model | DMDLおよびDMDLコンパイラ |
dsl/ |
Asakusa DSL | 各種DSLおよびコンパイラ |
testing/ |
TestDriver | テストドライバー |
directio/ |
Direct I/O | Direct I/O |
windgate/ |
WindGate | WindGate |
thundergate/ |
ThunderGate | ThunderGate |
yaess/ |
YAESS | YAESS |
administration/ |
運用環境の整備 | 運用環境へのデプロイメント手順等 |
product/ |
プロダクトについて | ライセンス条項やFAQ、対応プラットフォーム等 |
documentation/ |
Documentation | ドキュメントの書き方等 (内部向け) |
ドキュメントの形式¶
ドキュメントは Sphinx でビルド可能な reStructuredText 形式で記述し、拡張子は *.rst とする。
日本語¶
基本的には「ですます」で記述し、仕様書等は「だである」で記述する。
ドキュメントのターゲット¶
以下のうち誰を対象とするかを想定すること。
- User (U): Asakusa Frameworkを利用してバッチアプリケーションを開発する人
- Administrator (A): Asakusa Frameworkを利用して開発されたバッチアプリケーションを運用する人
- Manager (M): Asakusa Frameworkを利用してバッチアプリケーションを開発させる人
- Developer (D): Asakusa Frameworkそのものを読んだり、拡張ポイントを利用して拡張したりする人
- Insider (I): Asakusa Frameworkそのものを開発する人
標準的なドキュメント名¶
ありえそうなドキュメントの例。 下記に該当するドキュメントは、可能な限り名前をそろえる。下記に該当しないドキュメントは、命名規則の範囲で自由に名前をつけてよい。
| ドキュメント名 | 想定対象 | 内容 |
|---|---|---|
| index | 全員 | モジュールの概要や他のドキュメントの参照 |
| faq | 全員 | FAQ的なもの |
| start-guide | U, M | 最も簡素な方法でモジュールを利用する手順 |
| user-guide | U | バッチアプリケーション開発時に必要なモジュールの公開機能を可能な限り網羅したマニュアル |
| developer-guide | D | Asakusa Frameworkの拡張ポイントを利用した拡張ガイド |
| administrator-guide | U, A | 運用に関するマニュアル |
| log-table | U, A | ログ一覧 (コンポーネントに関してまとめて出す) |
| with-X | U, Aなど | 他のコンポーネントXとの連携方法 |
| [X-]specification | I | モジュール[のX (language, extensionなど)]に関連する設計書または仕様書 |