しらとりのブログ

社会人ひよこプログラマのtil

プロジェクトのドキュメントをMarkdownで管理した感想

silatori.hatenablog.com

以前にこんな記事を書きました。社内のMarkdown布教も進み、ついに成果物ドキュメントをMarkdownで管理していたプロジェクトが先日終了したのでその感想です。

前提

今回のプロジェクトは受託案件でした。機能要求ドキュメントだけお客様より頂き、納品物に設計書と試験仕様書を納品するタイプでした。もちろん提出するドキュメントの形式はwordを求められていました。 つまり、Markdownをwordに変換する必要があります。よくあるパターンだと思います。今回はPandocというMarkdown->wordに対応する変換ツールを使用してこの問題が解決されました。

運用

流れとしては最初にプロジェクトリーダがリポジトリにドキュメント用のフォルダと章項節をテンプレート化したMarkDownファイルを配置します。あとはpushをトリガにしてCIツール(今回はJenkins)からpandocコマンドたたいて納品物をまとめるサーバーに出力する。という方式がとられていました。この編の環境整備は私と同じくMarkdownを布教していた先輩社員と今回のプロジェクトリーダに整備して頂きました。

良かったこと

  • gitで差分管理ができる
  • gitサービス(今回はgitbucket)上でコメントとかIssueを付けれらる
  • メンバ間でドキュメントのクオリティ差があまりでない

やはり管理をMarkdownにした時点でgitで管理できるという大きなメリットがあります。更新に対するフィードバックが早くもらえるので、修正のサイクルもwordの共有モードでの管理よりかなり早いです。また、Markdown自体の記法が少ないことで良い意味で制限がかかりメンバ間でフォーマットに統一感が出ました。

問題点

  • 図形の調整ができない
  • 最後はやっぱりword上で調整が必要

UMLを記載するときはdraw.ioで作成して図で書き出し、参照という方法で対応しました。書き出しの手間が増えてしまうのは面倒ですが、draw.ioが保存するXMLもgit管理におけるので一長一短でした。そしてやはりpandocでwordに変換できるとはいえ、最終段階ではwordでの調整が必須です。ページングや改行の調整などを専門に行う人をたてて行われました。

まとめ

全体的にみると開発ドキュメントをMarkdownで管理すること自体は成功だったと思います。共有モードのwordファイルを更新するたびに周知してコメント機能で指摘を入れる…というよりはgitサービス上で内容を確認、修正コミットを依頼という流れがとても良かったです。最終的な調整もword変換後にテンプレートに合わせたマクロを動かすことで改善できそうな感じもあるので、今後もMarkdownでの管理は継続するでしょう。この流れでどんどんOffice依存を解消していきたいですね。

……来週から次のプロジェクトのキックオフ…まとまった休みが欲しい。。。