システム開発上の文書をどう書き進めるのがいいか

𝕂𝟚𝕐 @k2y

人に「システム開発上の文書をどう書き進めるのがいい？」と聞かれたので答えてみるテスト。

𝕂𝟚𝕐 @k2y

基本は、概要から詳細に理解が進むよう、章立てを分けて考えること。目的と手段を分けて考えること。

𝕂𝟚𝕐 @k2y

進め方としては、業務目的→目的が達成された業務イメージ→目的達成のための手段としてのシステム外部仕様→システムの内部仕様の概要→システムの内部仕様の詳細、のように進めるのが常道。

𝕂𝟚𝕐 @k2y

業務イメージは、たとえば業務フローで、外部仕様は、たとえば画面やユースケース、外部I/Fの定義。内部仕様の概要は、システム構成とか肝になる部分の通信方式やアルゴリズム、内部仕様の詳細は、個別のユースケースをどう実装するか。

𝕂𝟚𝕐 @k2y

というわけで、業務レベル（目的と完成イメージ）、システムの外部仕様レベル、内部仕様レベル、で分けて考えて構成作ってみるといい。ユーザは業務レベルがわかればよい、外部仕様レベルは開発者全員がわかればよい。内部仕様レベルは各担当開発者がわかればよい。想定読者が文書の章立て毎に変わる。

𝕂𝟚𝕐 @k2y

ま、これは一例ですがね。システムの特性とか、開発にかかわる想定読者のレベルによって、構成はアレンジする必要がありますが、基本としてこのくらいを意識するとよいと思うのであるよ。

𝕂𝟚𝕐 @k2y

これは読みやすい文書としての構成であって、分析・設計という作業の進め方とは必ずしも一致しないことに注意。分析から設計、設計の概要から詳細、というのは、往々にしてループする。ループを手戻りにならないよう進める進め方のコツは、また別のお話。

𝕂𝟚𝕐 @k2y

いずれにせよ、文書を書くときには「その文書の目的」を明確に意識して進める癖をつけるべきなのでありまして、無駄に大量生産する文書は負債・不良資産と思い知る、そんな経験も踏む意義はあるのかもしれぬ。が、自分が関わる案件では見たくない。

𝕂𝟚𝕐 @k2y

コンサルとしての文書作成も、概要から詳細、読者の頭の中になにが入ってるか文脈を意識しろ、は同じだが、文脈を狙って操作することもある、ってのが違う点ではあるなぁ。

𝕂𝟚𝕐 @k2y

時そばじゃないが、単純に「ひぃ、ふぅ、みぃ、よぅ……」と数えていけば、これはそういう話ねっと場の文脈が作れるわけで。そこで「いま何刻だい？」とうまく聞く構成。ま、そんな簡単じゃないがなー。