おいしいブログ

ドキュメントは手軽に書いていきたい話

どこにでも転がっている話ではあるけれど。

  • 仕様書なり設計書なり、ドキュメントを作る機会は結構ある
  • エクセルだけに収まっているうちはエクセル方眼紙は別に嫌いではないし、新メンバー、お客さん、外部ベンダー誰に渡しても一応は機能する
  • プロジェクト毎、同じプロジェクトでもフェイズによってフォーマット/スタイルが逐一違うのが面倒で、気にかけなければいけないのも負担
  • 日付のsuffix付きファイル大量発生、結局ファイルの更新日が一番新しいものが最新ファイル
  • 同じ名前のファイルが別ディレクトリに複数ある
  • 別紙参照を参照するのが辛い
  • モデリングツールやPPTで書かれたダイアグラムを画像化、貼り付けの更新手間爆発
  • なぜか貼り付けられている画像の元データが無い
  • 更新が手間すぎて更新されてない
  • メール添付で共有
  • 変更管理が手間
  • 同時編集によるファイルの競合、退行
  • etc, etc ...

単一のリポジトリで、テキストでピャッと書いて、参照先にシュッとすぐ移動できて、すぐ戻れて、何もせずに誰でも簡単に見ることが出来て、図ありテキストありの便利なツールで、メンテナンス負荷が高い高いと言われるドキュメントの手間を減らしたいというのはみんなが思っていることだろうと。

(まぁ、そういうメンテ作業を全くしないプロジェクト管理者にとっては自分ではやらないし、機能なんかとは違ってタスクの項目として上がらないので興味関心外になって、慣習によって脈々と不条理が強いられ続けるんだろうなぁ、と。)

さて、そんなことはさておき、お客さんの納品物として許容されるかということは無視して、本来HTMLってピャッ、シュッ、ビューンなリッチなツール。お手軽ドキュメント作成の雛形を作っておけばそれなりに使える場面もあるのでは?ということで作っておくことにしました。

mylde/gascii-doc - GitHub

  • plantumlで簡単ダイアグラム生成
  • swaggerで簡単API仕様生成
  • asciidocで簡単HTML生成

webのapi documentなんかを swagger で書いて asciidoc 化して、 plantuml でUMLなんかを作って、 asciidoc にペッと埋め込んでHTML化。これで手軽に要件定義書でも要求仕様書でも設計書でもなんでもいけますね。

Reference