nDiki : 要求仕様書

定型書式で内容を記述していくのに便利な形式は?

今要求仕様書を LaTeX で書いている。 要求と仕様の組をまとめて longtable で記述しているのだが、 LaTeX らしい繁雑さがあってちょっと効率が悪い。 マクロを定義すればある程度書きやすくなると思うが、それでもそこそこまでな気がする。

文書の中にレコードの並びが書けて、レコードの並びの中に文章が書きやすいそんなフォーマットはないものかなぁ。

• LaTeX + マクロ
  • 整形は綺麗。
  • 記述が繁雑になりがち。\マクロ名とか {} とか。
• DocBook
  • 仕様デカスギ
  • 以前使ってみたことがあるが、手で書くのにはしんどい。
• XML
  • 構造的な情報の表現には良いのだが、手で書くのはしんどい。開きタグも閉じタグも。
  • 普通の章節や、マークアップのルールを考えなければならない(定義するか借りてくるか)。
  • LaTeX等へのコンバータを書く必要あり。
• YAML
  • レコードの並びだけだったら良いが、文書の他の要素を一緒に書くのには適さない。
  • ある程度の構造やボリュームがあると、思ったほど手書きしやすくない。
  • YAML Perl モジュールで痛い目にあっている。

Wiki に慣れきっている自分にとっては Wiki 文法のような感じで記述できて、一部に定型レコードの並びが書けて、そこの整形ルールだけ定義してあげれば LaTeX に変換できるとかそういった感じがのものが欲しい。 定型レコードの部分は RFC822 のヘッダみたいな感じで良くで、値の部分に長めの文章を複数行で書けるものがいい。

構造化テキスト用フォーマット、あるいはWiki フォーマットをアレンジするのがいいかもしれないな。 このあたりのフォーマットは、ソーステキストのままでも十分読み易いことを意識して定義されているので書くのは楽。

• reStructuredText
  • いいらしい。
  • HTML、LaTeX、XML へのコンバータがある。
  • 拡張性も考慮されているらしい。
  • でも Python。
• Markdown
  • reStructuredText よりもソーステキストが読み易いらしい。
  • Perl
  • HTMLへの変換しかない。
• WiKicker (Wiki)
  • かなり書き慣れている。
  • レコードの並びの書き方を考える必要あり。
  • 複数行にまたがる処理を書くのが面倒。
  • 自分で書いているシステムなので中身は何でも知っている。
  • マイナー。

レコード部分とは関係ないけれど reStructuredText や Markdown の「アンダーラインのあるテキストを見出しとする」っていうのはいいな。 普段メールやプレーンテキストでちょっと文書を打つときに使っているスタイルと一緒だ。

要求仕様書用に使うかどうかは別として、要チェック。

早速 reStructuredText から LaTeX へのコンバータを書く

要求仕様書を書くのに reStructuredText を使ってみることにしる。 reStructuredText の文法の上で、あるルールに従って書いた特定のセクションやフィールドリストを要求レコードや要求仕様レコードとし、自前でコンバータを書いて LaTeX へ変換する形。

まずは最初のアイデア通り rst2xml で XML に変換してから、Perl スクリプトで読み込んで処理することにする。

Perl 側の処理は XML::LibXML で (何となく XML::DOM より好き)。 しかし毎度ながら DOM 面倒くさい。 とりあえず、今必要な要素のみ変換コードを書く。 reStructuredText を XML へ変換した時の DTD があるので、おいおいこれを見ながらきちんと埋めていかねば。

最低限のものができて、早速コンバート。

これで生 LaTeX で書くより随分楽になった。よし。

Docutils は自分にとっての Python キラーアプリかも

先日 reStructuredText ベースの要求仕様書ファイルから、LaTeX への変換プログラムを Perl で作成した。rst2xml で変換した XML 文書経由で。

欲しいところだけまずは実装して使ったんだけれど、この先使っていくには細かいところを組んでいく必要がある。やっぱりフルスクラッチするのは面倒だな。

本来は Docutils 用の Writer を作成するのが王道。

しかし Python なんだよね。以前に何度か覚えておこうと思ったんだけれど動機づけが弱かったのかいつも途中でフェードアウト。 しかし今回は明確な目的があるので、もりもりやりそう。

まずは既存の docutils.writers.latex2e.py あたりをコピーしていじって遊んでみるかな。 自分の場合この方法が一番覚えるのが早い。 小学生の時に最初にBASICをいじった時も、既存のゲームのパラメータとか改造から入ったし。

さて、その latex2e.py であるが「documentclass がオプションや設定ファイルで変更できるものの、標準の LaTeX2e 用のもののどれかしか駄目」だったりなど、普通に使うにもちょっといじる必要がありそう(jsbook とか使いたいし)。

一旦自分好みの LaTeX2e Writer を作ってから、それを拡張する形で特定文書毎の Writer を作るのがよさそうだ。

第10回 社内 Perl 勉強会

リャマ本を使用した社内 Perl 勉強会の10回目を開催。今日は6人。

今日は「初めてのPerl 第3版」第11章「ファイルハンドルとファイルテスト」が範囲。

@ 今回の反省点

今回はパーミッションの話など Windows 環境よりも UNIX 系環境の話が多かったのだが、皆慣れてきたのか特に大きな混乱はなかった様子である。

open / close はそれこそ頻繁に使うのであるが、本書では思ったよりライトな扱いな感じ。

初めてのPerl 第3版の練習問題は、いままで問いてみて「確信犯的」に問題があいまいに書かれている。 要求仕様書だったらまずいかもしれないが、練習問題だと頭を使うので悪くない。 また他人をまじえた回答レビューでも他の読解によるプログラムを見られたりして、単純な答え合わせ以上の理解ができ面白い。

今日のさえずり: 帰ってきたら笹が!

2010年07月06日

• 07:14 36.8℃。
• 07:27 @ishiduca ありがとうございます。今日は出社します。
• 11:23 要求定義書/要求仕様書には複雑でややこしく実装に手間がかかるところほど、さらりとしか書かれていない件。
• 12:07 お昼 473円。 (@ セブン-イレブン神田佐久間町店) http://4sq.com/cEfW1k
• 13:19 缶コーヒー 100円。
• 13:23 HootSuite ようやく OAuth 対応してたか。これで使ってみることができるよ。
• 16:37 K-9 Mail で複数アカウント扱えるのだけれど、メールアドレス補完はメインの連絡先だけなんだな。 #Android
• 19:14 病み上がりというか、まだ上がっていないので定時退社。
• 19:20 会社に傘忘れてきた。 (@ 秋葉原駅 w/ 12 others) http://4sq.com/68fhHr
• 19:33 HootSuite OAuth 対応記念に、再び HootSuite Lite 入れてみた。 #Android
• 20:00 Evernote 共有ノートブックのフィードを FeedBurner 経由で Twitter に投げるの止めた。フィード自動投稿設定しておくと気軽にノートできないことが判明。
• 20:10 帰ってきたら笹が!
• 21:21 短冊に願い事書いて吊るした。これでバッチリだ。
• 21:27 今年は水着買いたい。
• 23:12 特別区民税・都民税の年税額が12で割り切れなくてとても困る。
• 23:13 4期への配分で1期分だけ多くしているのは、500円単位にしたいからなのかな。
• 23:20 RT @America_Amazon: 実はTL上でよく見かける「API」というものが何なのか、まったく理解していません。ご存知の方がいらっしゃいましたら「ダイ・ハード」に例えて説明していただけると助かります。APIの内のどれがブルース・ウィリスに当たるのでしょうか……。

プロジェクトでみんなをバスに乗せるために書いておく項目リスト

みんなをバスに乗せるためにプロジェクトのプランニングで明確にして共有した方が良いドキュメント形式って、方法論やプロジェクトの段階によっていろいろな名前のものがありますが、基本的に項目はどれも似たような感じです。

項目名を整理して決めておくと楽なのでちょっと書き出してみました。

コンセプトシート

比較的軽量にまとめる時。

• タイトル
• 概要 (What)
• 目的(と背景) (Why)
• ゴール (Goals) and/or 目標 (Objectives)

プロダクトプラン

プロダクトプランニング(エンビジョニング)のアウトプットとして。エピックレベル(数カ月程度の大きさ)。

• プロダクト名
• プロダクトビジョン
  • 概要
  • 目的(と背景)
  • ゴール and/or 目標
  • 成果物
  • 完了条件
  • スコープ(含むの・含まないもの)
  • (opt) 依存するプロジェクト・制約条件
  • (opt) リスク
  • (opt) 予算
  • (opt) メンバ
• 概要レベルのプロダクトバックログ
• プロダクトロードマップ

ポートフォリオバックログアイテム

ポートフォリオプランニングで、プロダクトプランを評価した結果のもの。エピックレベル(数カ月程度の大きさ)。

• プロダクト名
• プロダクトプラン
• 期間
• 遅延コスト(ビジネス価値・時間価値・リスク軽減/チャンスと利用)
• WSJF

プロダクトバックログアイテム

スクラムで1スプリントで完成できるサイズのアイテム。フィーチャーレベル。

• プロダクトバックログアイテム名
• ユーザーストーリー(誰・概要・目的・目標)
• 満足条件(あれば成果物を含む)
• サイズ
• レビュー方法

タスクチケット

ちょっとしたタスク。

• タスク名
• 概要
• (opt) 目的と背景 (概要で自明でない場合)
• (opt) 成果物/アクション (概要で自明でない場合)
• 完了条件
• 期日

プロジェクト憲章

• プロジェクト名
• 概要
• 目的と背景
• ゴール and/or 目標
• 成果物
• 完了条件
• スコープ(含むもの・含まないもの)
• (opt) 依存するプロジェクト制約条件
• (opt) リスク
• (opt) スケジュール・期限
• (opt) 予算
• (opt) メンバ

備考

他には以下のような形式もあります。

• One Pager
• インセプションデッキ
• 製品要求仕様書 (PRD: Product Requirements Document)
• リーンキャンバス

[ プロジェクトマネジメント ]