Home » スタッフBlog » 継続的ドキュメント管理

継続的ドキュメント管理

category : スタッフBlog 2017.1.5 

新年あけましておめでとうございます。
技術部の久保田です。

アジャイルやウォーターフォールのモデルの違いによってその量や質・目的は異なれど、
システム開発においてドキュメントは欠かせません。

今まで見てきた設計書はだいたいExcel形式のファイルに記述されておりました。
やはり扱いやすさや表現方法の多さなどから
(またはお客様への納品物というケースもあるかもしれませんが)ExcelやWordが選ばれるのでしょうね。
できたてホヤホヤのExcel設計書なんかそれはもう大変に美しく、
これから出来上がるであろうシステムを夢想して胸が熱くなり感無量となるのであります。

最初のうちは。。。

ところで皆様、こんな経験ありませんか?
 ・現行システムの維持管理を任されて渡された設計書の拡張子が「xls」。
 ・Excelファイルの1番左のシート名が「修正履歴」で内容が2年前で止まっている。
 ・いくら探しても見つからないネットワークPCの何かのBookのどこかのシートを参照している。
 ・ファイルが多すぎる。ファイルサイズが重すぎる。シート数が(略
 ・要は設計書がまるで役に立たない。

そんなとき、こう思ったことはありませんか?
「いつかこのドキュメントをメンテナンスしなきゃな。。。」

そんな日は来ません。(正直に言えば目を逸らし続けたい。。)

Excelで作成されたドキュメントってメンテナンスにコストがかかるんですよね。
ファイルを開いて(重い!)、シートを跨いで修正対象を探して、修正して、修正履歴に追記して、
次のファイルを開いて(重い!)、の繰り返しなわけです。
で、レビュアーは更新されたファイルを開いて以下省略。

とはいうものの、ある種のドキュメントはメンテナンスを継続する必要があるわけです。
システムの稼働後は保守フェーズとなりますが
システムの開発者がそのまま保守の担当者になるとは限りません。
特に保守は数年のスパンですから、必ず「引き継ぎ」が発生します。
新しい保守の担当者は対象となるシステム(プログラム)の内容を理解しなくてはいけないのです。

ではどうやってドキュメントを継続的に(楽に)維持し続けるか?

一つの解決策として、以下の書籍が参考になるかと思います。
http://gihyo.jp/book/2016/978-4-7741-8036-6
幾つか抜粋して紹介しますと、

1.軽量マークアップ言語での記述
 ドキュメントを軽量マークアップ言語で記述します。
 メジャーなところではMarkdownですかね。
 弊社はプロジェクト管理ツールにRedmineを利用していますが、
 チケットやWikiはMarkdownで書いております。
 学習コストは低く、それなりに表現力のある文章を書くことができます。

普及率ではMarkdownに劣りますが、AsciiDocという言語もあります。
Markdownよりも表現力があり、Markdownのように方言がない(言語仕様が定められている)
という利点があります。
ただ記法が多いので、Markdown⇒AsciiDocという順で学習するのが良いかと思います。
オフィシャルな操作マニュアルなどのドキュメントに適していると思います。

2.バージョン管理システムを利用
 ドキュメントをプログラムのソースと同様、GitやSubversionなどで管理します。
 軽量マークアップ言語で記述したドキュメントはテキスト形式なので、
 GitやSubversionなどのバージョン管理システムとの相性がとても良いです。
 修正履歴は差分としてひと目で分かりますし、マージ作業もシンプルになります。
 OS毎のインストールマニュアルみたいなドキュメントを各ブランチで管理、なんてことも可能ですし、
 GitHubなどのサービスを利用すればプルリクエストでドキュメントのレビューもできますね。

3.PDFやHTMLへの出力
 軽量マークアップ言語自体、可読性は高いのですが、
 お客様への納品物やWebシステムにマニュアルを付けるケースが発生した場合、
 別フォーマットに変換する必要が出てくるかもしれません。
 AsciidoctorというAsciiDocをHTMLやPDFに変換できるRuby製ツールを利用することで解決可能です。
 他にも文書校正ツール(RedPen)やCIサービス(TravisCI)によるドキュメントの品質向上など、
 興味深い内容ですのでオススメです。

以上、継続的なドキュメントの管理手法として1例を挙げてみましたが、
技術者として、常に変わっていくシステムのドキュメントをメンテナンスし維持することの必要性、
重要性の認識が必要不可欠かと考えております。
メンテナンスさえしっかりとしておけば、場合によってはExcelでも良いわけです。(見た目きれいですし)

私としては、まずはAsciiDoc+Gitから段階的に進めていきたいな、と新年に誓う次第です。

本年もよろしくお願い致します。

タグ

サイト内検索

Copyright(c) 2017 IT-TERA All Rights Reserved.