ドキュメント管理

githubを使用している事もあり、各アプリ、フレームワークに添付するドキュメントのフォーマットには、markdownを使用しています。

APIの説明など、定型的な章立てを使うドキュメントが多いです。この様な文書をフリーフォーマットのテキストで管理するのは管理が困難だと気づき始めました。Domain Specific Formatを定義して、入力テキストがそれに沿っているか確認しつつ、markdown文書を生成するツールが必要だと考えます。

ツールの要求仕様をまとめました。

• 入力
  1. テキストの入力フォーマット(DSF: domain specific format)の定義
  2. 上記フォーマットをmarkdownフォーマットに変換するルールの定義
  3. 入力テキストファイル (複数指定可)
• 出力
  1. markdownフォーマットのテキストファイル

DSFとルールの提議方法がキモですね。