Excel の
まとめた
設計ドキュメントを Web化したい 欲求を 持つに 至る 原因
Web化したい
個人的な
Excelだと
差分が わからない
Excelだと、以前の Versionとの 差分が わからないため、 変更箇所の 色を 変える 場合が あります。
Excel間のDiffを 取る 方法も ありますが、 Excel以外の ツールが 必要に なります。
Excelファイル同士をdiffする ための 方法 - Qiita Googleスプレッドシート、
ドキュメントだと 組織外への 共有が できない 場合が ある
個人的に、ブラウザで 編集が でき、 共有も できる Googleスプレッドシート、 ドキュメントでの 設計書作成は 快適に 思いますが、 組織内の みへの 共有を 許している 場合、 組織外部への 共有は できません。
外部への共有は、 結局 Excel化が 必要で、 そうなると 外部の ユーザーは 編集が 難しい 可能性が あります。 案. 組織内と
組織外が 作成する ドキュメントを 明確に 分ける
Google スプレッドシート、ドキュメントの デメリットを 記載していて、 組織内と 組織外で 作成する ドキュメントを 明確に 分けてしまうと いう 案が 浮かびました。
基本設計は、組織内で、 詳細設計以降を 組織外へ 依頼する ケースなどこの 方法で いいかもしれません。
Google スプレッドシート、ドキュメントに する ことで、 Google Cloud Search の 恩恵を 受ける ことができます。 その
場限りの ドキュメント問題
0-1フェーズ後の、1-100フェーズに 入ると、 システム変更要点のみを まとめたい ケースが あります。
その際の ドキュメントは、 システム変更要点を まとめているが、 システム変更時のみ 使われ、 その 後利用される ことがない ドキュメントに なります。
検索が容易な 仕組みが 存在する 場合は、 変更後も 利用されるかもしれませんが、 Excel設計書の 場合、 個人的に 検索性が 悪く、 使用される ケースが 個人的な 経験上は ありません。
またこの ケース、 0-1フェーズで 作成された 設計書が メンテナンスされないと、 ドキュメントの 信頼性が 失われ、 ドキュメントを 参照する 人が 少なくなります。
設計ドキュメントの Web化に あった ほうが いい 機能
設計ドキュメントの
他にもあるかもしれません。
- GA に
よる Web解析 - 読まれない
ドキュメントを 見つける - 読まれない
ドキュメント - 価値が
ない。 捨てる。 - 価値が
あるが 知られていない。 - 宣伝する
- 価値が
- 読まれない
読まれる
ドキュメントを 見つける - 宣伝する
- 宣伝する
コンテンツレコメンド
似ている
設計書を 探す。 アイテムレコメンド。 - Wikiだと
良い 感じにできるが、 設計ドキュメントで 良い 感じになるかは 実際に やってみないと わからない。
- Wikiだと
協調フィルタリング
- この設計書を
見た人は、 この 設計書も 見ています を 実装する。 - GAでの
データを 元に 協調フィルタリング は 実現できる。 この 際、 コンテンツレコメンドで 上がってくる 設計書は 除外する。
- この設計書を
ツリーと
カテゴリ、 タグ
ツリー、カテゴリ、 タグも あった 方が 良い 機能かと 思います。 ツリー
- ツリーは
機能単位。
- ツリーは
カテゴリ
- ドキュメント種類に
対する カテゴリ、 例えば 画面遷移図
等
- ドキュメント種類に
キーワード
- これは
用語辞書に 登録するような キーワード。 業務用語。 - 文書の
形態素解析で 取り出すのも 良さそう。
- これは
全文検索
- 静的サイトジェネレータだと、
見出し、 タイトルの 検索までが 多い。 - Wiki のような
ツールだと 全文検索が できるが、 版管理が 難しそう。 静的サイトジェネレータ と
何かの 全文検索の 組み合わせが 良い気が する。 文書校正ツール
ツール候補
- TextLint
- Redpen
構成管理に
チェックインされた マークダウンを CIで 校正ツールで チェックする。 版管理
- 版管理が
できる こと 静的サイトジェネレーターだと
マークダウンが テキストで 版管理される。 ドキュメント監査
これは機能ではなく 考慮。
内部監査などがある 場合、 監査に 必要な 観点が Webの ドキュメントで 担保されている 必要が ある。 UML等の
ダイアグラムが かける - 案1 画像を
使う - 画像生成元ネタが、
テキスト形式の ファイルであれば 構成管理上に 載せて おけば 見れる。
- 画像生成元ネタが、
- 案2 作図ツールを
使う - 作図系ツール・ライブラリまとめ
- 個人的には、
mermaidを 使ってMarkdownで シーケンス図を 作成 - Qiita が 良いと 思った。 - ホワイトボードに
書いた クラス図なりを、 画像に して、 手書きで 補足を するのが、 ベストプラクティスにも 思う。
既存ドキュメントの 移行
既存ドキュメントの
ドキュメントサイト作成時に
Excel からの
移行
kyokomi/excel-to-markdown: excel to markdown convert toolRedmine からの
移行 Pandoc を
使う
Pandoc ユーザーズガイド 日本語版 - Japanese Pandoc User’s AssociationRedmineは
Web API が あるので、 Texttileを 取得して、 変換する ツールを 作成すれば、 多少の 情報欠落を 容認すれば 移行は 比較的容易かもしれない。
実はExcelドキュメントでも 問題が ない パターン
よくよく
開発規模が
大きくない。
システム改修の開発規模が 小さく、 原本直接編集でも 何とかなる レベルの 規模感。
そもそも 全体の ドキュメント数が 少ない、 人間が 十分仕様把握できる 規模。 並行開発で
競合する ドキュメントが そこまで 多くない。
並行開発が行われているが、 開発ラインで 設計書類の 重複が 少ない。
本線修正でも競合リスクが 少ない。 構成管理から
ドキュメントを 取り出すと いう 行為が 面倒なだけで、 Excelで 事が 足りている - 構成管理に
ファイルを 配置する タイミングを 変更する。 - 構成管理から
取り出しやすくする ツールを 作る。
今のと
以上です。
コメント