以前社内勉強会で使用した資料があったので公開します

1. ドキュメント改善
2014/09/22 KAWAKAMI Fumio

2. 自己紹介
• 川上 文夫(1988年よりシステム開発に従事)
– RPG, COBOL, C, Perl, sh, Java, JavaScript, Python,
Scala
– 2000年ごろからAgileを取り入れたプロジェクト推
進を実施
– イテレーション、ドキュメント関連が得意(と思っている)

3. ドキュメントとは
• 開発中のドキュメント
• 開発終了時のドキュメント
• 開発終了後のドキュメント
• 何をどう作るかは重要ではない
• 何故どのように作ったかは重要

4. 石器時代のドキュメント

5. 1970年代まで
• 局面ごとに作成
• 作成されたら変更されない
• 変化が激しくない時代に向いている
– 仕様は変わらない
– 環境は変わらない
• PC, Smartphone, tablet
• Network, Security
– 競合も変わらない

6. 現代のドキュメント

7. 21世紀ドキュメント
• 動くコードとドキュメントは同期しなければなら
ない
– そのドキュメント、古いです。
– あちらは修正したのですが、こちらは忘れていま
した。
– Brush up anytime, anywhere

8. 検索
• 「あの仕様はどこにあったっけ」
• 「Aフォルダの下のBフォルダの下の...」
• 「ABC機能(DEF受信).xlsxというファイルかな?」
• 「いえ、ABC機能(DEF連携).xlsxだったと思いま
す。」
• 「ファイルを選択して、開いてっと。あれ、ない
よ。」
• 「Aフォルダの下のBフォルダの下のEフォルダの
下のABC機能(DEF拡張).xlsxだったかもしれませ
ん」

9. わかりやすさ
• ある日
– 「XXX機能ってどんな機能ですか?」
– 「それは、XXXはYYYで....」
– 「どこかに書いてありますか?」
– 「みんな知っているから書いてないんじゃないか
な」
• 3ヶ月後
• 「XXX機能ってどんな機能ですか?」

10. わかりやすさは固定ではない
• 今、わかりやすいと思うドキュメントでも、明日
わかりやすいとは限らない
– 読む人によってわかりやすさは違う
– メンバーが変更されれば暗黙知は失われる
– 他の機能が変更されたため、意味がかわってい
た、というケースも

11. 修正しやすさ
• 「XXXにYYYの記載がありません。わかりにくく
ありませんか?」
• 「そうかもしれないけれど、修正が必要なほど
の問題じゃないね。」

12. レビュー済み文書
• レビュー済み文書はよっぽどのことがないと
変更できない
• 変更には手続きが必要(!?)、面倒
• 「多分更新しなくても、みんなわかるんじゃな
いかなぁ。」

13. • システムは一部修正すると意外なところにバ
グが発覚します。
• ドキュメントも一部修正すれば、意外なところ
も修正しないと不整合になります。
影響範囲

14. Regional Scrum Gathering® Tokyo
2014

15. 常時レビュー
• Wikiを使うことにより、常時レビューが可能
• 開発者は常にWikiを参照、修正しています
• わかりにくい箇所、記載漏れを見つけたらそ
の場で修正します
– 必要に応じて定例会議で報告
– 無限履歴管理

16. 修正のしやすさ
• ちょっとした修正の積み重ね
– Word/Excelだと開くのが面倒
– Word/Excelだと巨大ファイルを開いて1箇所修正、
巨大ファイルを更新
– Wikiなら、ブロック編集

17. Wikiで全文検索
• Wikiにドキュメントを集約
– 要件, 設計書, 議事録, 通達事項
– あれはワード, これはメールとならない
– 常にみんながWikiを見ることで修正漏れ、最適な
記述を維持できる

18. ドキュメントよりソフトウエア
• Wikiを使うことでドキュメント作成時間の短縮

19. デメリット
• 印刷には向かない(レイアウト変更は難易度
大)
• 一覧、表計算、グラフ、イメージの添付は工夫
が必要(通常WikiとExcelを併用します)
• 別の意味でのドキュメントスキルは必要

20. 実績1
• メーカー、常時30人参加プロジェクト
– 関連チーム含めると100名以上
– 海外向けパッケージ製品
– 初年度、Wikiを使うことをテーマにプレゼン、条件
付きで認められる(マイルストーン毎にWordへの
転記)
– 当初は自分のサブチームが利用の80%
– 半年後ぐらいからWord文書化されずWikiのみ
– 1年後には30名全員が書き込んで利用していた

21. 実績2
• プロトタイプながら国家入札プロジェクト、
Redmineにて管理、納品(納品はWikiを静的
HTML変換)
• 官公庁プロジェクト。国内メーカーが一次受け。
メーカーチームのサブチームにてWiki文書管
理採用。

22. 納品物
• ご希望に合わせてWikiをPDFにして納品可能

23. 最後に
• Wikiを採用することにより適切な品質のド
キュメントを未来まで維持できます。
• ぜひWikiの導入をご検討ください