システム開発用のドキュメントツールはローカル保存のテキスト形式が良い

2022年6月2日木曜日

システム開発

t f B! P L

一般のドキュメント作成ツール

企業などの事務処理で一般的に使用されるドキュメントツールはMicrosoftのWord, Excel, Power Point が主流だと思う。
ITベンダーの中のWebアプリを中心に製品開発している企業だと、Google Workspace 系のGoogleドキュメントやGoogleスプレッドシートになると思う。
Markdown形式のドキュメントを作成しているところも多い。
 
他にも昔からUMLやフローチャート・ガントチャート・クラス図・ER図・WBSなど、計画や管理・設計に必要なドキュメントを作成するツールがたくさん提供されている。
 

二種類のドキュメントツール

現在の事務処理用ドキュメントツールは、大きく分けて二つに分かれる。
 
ローカル保存系とクラウド保存系だ。
 
一つは旧Microsoft Office系のWord, Excelなどのように、スタンドアロン・アプリケーションとして作られたソフトウェアで、文書ファイルをローカル・ストレージに保存する形式になっている。
テキストエディタやMarkdown形式のドキュメントもローカルに保存する方式になる。
 
昔はネットワークの通信速度が不十分だったため、ドキュメントツールは全てローカルのハードディスクへ文書ファイルを保存していた。
 
一方、Google系のGoogleドキュメントやGoogleスプレッドシートなどのツールは、Googleのクラウド・ストレージに保存される。
ローカルにはファイルの実体は保存されない。
エクスプローラから見るとローカル・ストレージにファイルが存在しているように見えるが、あれは編集対象にしたときにクラウドからローカルへファイル単位でダウンロードして編集できるように作られているだけで、ローカルに永続的に保存しているわけではない。
他社のクラウド系のドキュメントツールも、文書ファイルはクラウド上にアップロードされローカルには保存されない。
 
最近はサブスクリプション契約をしやすい為か、クラウド系のドキュメントツールが増えている。
 

システム開発用の文書

会計財務など一般の事務処理の場合は知らないが、システムやソフトウェア開発の場合は、設計書や仕様書・計画書・課題リストなど、システム開発に関連する文書は、システムのソースコードと一緒に、バージョンごとに履歴管理できると便利だ。
システムやソフトウェアはバージョンアップするごとに仕様が変わっていくものなので、バージョンごとの仕様書や設計書を別々に保存しておかないと、過去のバージョンの仕様が分からなくなってしまう。
 
アジャイル開発などを行っている場合、いくらアジャイルが可能な限りドキュメントを書かない手法だとしても、業務手順や規格などは仕様書に残さなければならない。
ER図などデータ構造の仕様書などは、無くせないだろう。
計画や課題リストなどの人間側業務の文書などは、いくらアジャイルでも必要だ。
そしてアジャイルは開発周期ごとに仕様を追加変更していく開発手法なので、必然的に仕様書など文書は、毎回書き換えられていく。
 
だからバージョンごとの文書管理が必須となる。
 

バージョン管理ツールによる文書管理

バージョンごとにソースコードや文書ファイルを保存する為には、Git やSVNと言ったバージョン管理ツールに文書ファイルをアップロードして保存する必要がある。
バージョン管理ツールはリポジトリと呼ばれるデータベースに過去にアップロードした文書ファイルを世代ごとに全て保存している。
過去の文書を取り出して、現在の文書と比較したりすることができる。
間違った編集をしてしまった場合も、過去に遡って編集前の文書に戻す事ができる。
 
GitHubというのは、このGitというツールを中心に作られたWebサービスである。
主にソースコードとドキュメントのバージョン管理と保存と公開を目的としたサービスだ。
次々と修正更新を繰り返す文書の公開に向いているソーシャルメディアとも言える。
バージョン管理ツールでは、複数の人間がバラバラに編集更新することが可能になっている。
何度も編集を繰り返し、清書が出来た節目で、バージョン番号を振って公開する事ができる。
 
このバージョン管理ツールは、編集履歴をテキストの差分で比較照合し保存する仕組みになっているので、文書ファイルはテキスト形式ファイルが望ましい。
 
MicrosoftのOffice系のWord, Excelなどの文書ファイルは、バイナリファイルなのでバージョン管理ツールとイマイチ相性が悪い。
バージョン管理ツールで使えないわけでは無い。使い難いのだ。
 
複数人のチームでバージョン管理ツールを使用し、ドキュメントを共有していたとする。
この時、チームメンバーの二人がある一つのドキュメントを、それぞれバラバラに編集して登録したとする。
 
このドキュメントの編集ファイルは二つになってしまう。
これをコンフリクトと呼ぶのだが、この二つのファイルをバージョン管理ツールではマージする事で一つに統一する。
 
マージとは、文書の二つの異なる変更を整合性の取れた形で合成して一つにする事だ。
例えば「登録ボタンをクリックする」という原文があるとき、
吉田さんが「登録ボタンをクリックする」変更し、
佐藤さんが「Ctrlキーを押しながら登録ボタンをクリックする」と変更した場合、
両者を合成して「Ctrlキーを押しながら登録ボタンをクリックする」とすることをマージと呼ぶ。
 
このときバイナリ形式だと自動でマージできない。
人間が相談しながらバイナリファイルを手動でマージすることになる。
当然、マージするときはWord, Excelなどツールを起動する必要がある。
 
数が増えるとかなり面倒になる。
 
テキスト形式ファイルならドキュメントツールを起動する必要が無い。
通常は自動でマージでき、できない場合も全てテキストエディタだけで済む。
また、マージする人がドキュメントの内容を把握している必要も無い。
規則に則ってマージ作業をするだけである。
 
だからバージョン管理ツールに登録するドキュメントは、テキスト形式ファイルである必要がある。
 
よってシステムやソフトウェア開発企業では、テキストファイルのMarkdown形式で仕様書を書いているところも多い。
Markdown形式の文書はGitなどのバージョン管理ツールととても相性が良い。
 

バージョン管理を意識しない主流派ツール

しかし、現在普及している主流派のドキュメントツールは、このGitなどのバージョン管理ツールと相性の悪いツールばかりが開発されている。
新しく登場したドキュメントツールも、最近はクラウドへ文書を保存する形式が多く、ソフトウェアのソースコードと一緒に文書を世代管理するには向いていない。
 
少なくともソフトウェア開発を中心に捉えた「ソフトウェアファースト」なドキュメントツールにはなっていないと私は思う。
 

バージョン管理に最適なドキュメントツールの条件

私が思う、ソフトウェア開発を中心に捉えたドキュメントツールは以下の条件を満たすものだ。
 
(A)スタンドアロンのソフトウェアである。
(B)文書ファイルをローカルのストレージへ保存する。
(C)文書ファイルはテキスト形式のファイルである。バイナリ形式ではない。
(D)文書ファイルは一文書一ファイルとなっている。複数ファイル構成ではない。
 
 

クラウド形式ツールの利点と欠点

クラウド形式ツールを全否定するわけではないが、文書のGitによる世代管理ができないのは事実だ。
 
Googleドキュメントのようなクラウド形式ツールは、文書をリアルタイムにグループ内で共有するのに優れている。
共有するために、わざわざ共有サーバーを用意する必要も無い手軽さにも優れている。
常に最新文書だけを残し、共有するだけなら、クラウド形式ツールの方が優れている。
 
問題はソフトウェアのソースコードと一緒に文書を格納できないことと、編集の世代管理ができないことだ。
クラウドツールの中には世代管理のできるものもあるが、単独の世代管理になっているので、ソースコードや他の文書と同期を取った世代管理ができないのが欠点だ。
 
UML、ER図、クラス図、基本設計書、詳細設計書、外部仕様書、WBSにガントチャート・アローダイアグラムに不具合一覧・仕様変更管理など、バージョンごとに管理したい文書は多い。
これらは個々の文書事にバラバラに世代管理していても意味が無い。
バージョンごとにグループ単位に世代管理する必要がある。
 
バージョン1.1 のソースコードや設計書・不具合一覧と、バージョン2.1 のソースコードや設計書・不具合一覧とが、それぞれ纏まっている必要がある。
 
過去のバージョンに遡ったとき、いちいちバージョン1.1 のソースコードとバージョン1.1 の設計書と、バージョン1.1 の不具合一覧とを、個々バラバラに集めて比較照合などしていられない。
 
そういう意味で、最近流行のクラウド形式ドキュメントツールは、仕様書などソフトウェア用の文書ツールとしては、良くないと思う。
 
MicrosoftのOffice形式もバイナリ形式なので良くない。
 

理想はスタンドアロンのMarkdownエディタ

理想はスタンドアロンのMarkdown形式ツールだ。
私が使っているのはTypora という Markdown エディタだ。
 
ただ、Markdown形式は文章しか書けず、表計算やUMLなど図表は書けない。
機能が少なすぎるのが欠点だ。
 
Markdown エディタのようなスタンドアロンのテキスト形式ドキュメントツールがもっと色々あっても良いと思う。
テキスト形式の表計算ソフト、テキスト形式の作図系ソフトなど。
 

釈明

一般の事務処理に使用する限りにおいては、特に必要の無い話ではある。
MicrosoftのOffice や、Googleドキュメントなどのクラウド形式ツールの存在まで全否定しているわけではないので、誤解の無いように。
 
また、スマホやタブレットでの文書の共有なども考えれば、クラウド形式ツールに優位性がある事は百も承知だ。
 
あくまで、システムやソフトウェア開発に特化した文書ツールの話である。

広告

このブログを検索

Translate

人気の投稿

自己紹介

自分の写真
オッサンです。実務経験は Windows環境にて C#,VB.NET ,SQL Server T-SQL,Oracle PL/SQL,PostgreSQL,MariaDB。昔はDelphi,C,C++ など。 趣味はUbuntu,PHP,PostgreSQL,MariaDBかな ?基本無料のやつ。

QooQ