これまで、Wordの使い方を覚えた方が早いのは理解しつつ、設計書や仕様書といったドキュメントを気軽に書く方法を模索してきました。
これまでの取り組み
reST + rst2pdf
- 方針
- reSTとrst2pdfを使ってドキュメントの内容と見た目を分離。
- 便利ツールの稼働環境をdockerでコンテナにすることで、会社のWindows上での動作を実現。
- 結果
- 気軽にドキュメントを書く（Sphinx + rst2pdf + LiveReload + docker）
- PDF作成ツールのrst2pdfの情報が少なく、見た目を拡張することに限界を感じた。
- reSTよりもMarkdownを使いたくなった。
markdown + pandoc
- 方針
- コンテナの利用は継続。
- PDF作成ツールとして、rst2pdfの代わりにpandocを利用。これによりMarkdownを利用可能に。
- rst2pdfでは実現できなかった見た目の拡張性をtexで頑張ることにした。
- 結果
- doc-man
- pandocで日本語pdfを生成するためには日本語Latexの環境を用意する必要がある。これが気軽ではない。
- 一からtexの作法を学習するコストが高すぎる。
- 会社のマシンがSSDになりディスク容量が激減。ローカルに執筆環境のコンテナで持つことが厳しくなってきた。
Atom + PDF印刷
- 方針
- コンテナをやめる。
- 見た目はCSSで頑張る。さようならtex。
- 結果
- Atomを使って議事メモをmarkdownで書き、Markdown Previewで確認、そのままHTMLに保存してPDFとして印刷。
- 議事メモ等の気軽な文章を気軽に作成する事には向くが、壮大な文章を気軽に書くことに不向き。
- 表紙や目次などが含まれるちゃんとしたドキュメントの作成に向かない。
現在の取り組み
上記の紆余曲折の結果、以下の形で試行錯誤を継続中です。
- 方針
- 壮大な文章（設計書や仕様書）を気軽に作れる環境を目指す
- 元ネタとなるプレーンテキストはMarkdownで書く。
- PDFの見た目は、CSSで頑張る。CSSで出来ない装飾はあきらめる。過剰な装飾はいらない。
- 執筆環境をローカルのコンテナ上で動かすのをやめる。ローカルではテキストを書くだけ、管理やビルドはリモートのリポジトリに任せる。
- 進捗
- md-kumihan
- このMarkdownが、コマンド一つでこのPDFになります。
- md-kumihanをGialabのリポジトリ上に配置し、ローカルでMarkdownを編集してPushすると、gitlab上のgit-hookやCIツールでPDFを自動ビルド、さらにリポジトリのwikiページにpdfへのリンクを作成とかもできます。
ドキュメントを中心とした継続的な運用改善
現在の会社では、運用チームのリーダとして継続的な運用の改善を生業としています。ちゃんとやれているかは、かなり疑問ですが。。
運用の仕組みはドキュメントにする必要があります。ですが、その時間は限られています。運用の仕組みは継続的に改善する必要があり、改善の結果はドキュメントに反映させる必要があります。ですが、その時間も限られています。
限られた時間の中で効率よくドキュメントを作成し、改定し続けるにはどうすればいいか。自分の中の一つの仮説が「気軽にドキュメントを書く」と「ドキュメントを中心とした運用改善」です。
時間がない中でまとまった文章を書くためには気軽である必要があります。限られた時間は文章の内容を作成することに注力し、見た目はツールにお任せする事が望ましい。これが「気軽にドキュメントを書く」という考え方です。
運用の仕組み＝ドキュメントですから、運用の問題点はドキュメントの問題、運用改善のゴールはドキュメントの改定です。運用の問題点は、随時ドキュメントのIssueとして起票し、対応方法を検討し実践していく。問題点の改善が完了したら、改善点を反映させるためのWIP Marge Requestを作り、ドキュメントの改定作業を実施する。運用改善のタスクが、対応するドキュメントのリポジトリを中心にして回っていく。これが「ドキュメントを中心とした運用改善」です。
こんな世界も悪くないんじゃないかなと考え、仮説を検証中です。「気軽にドキュメントを書く」と「ドキュメントを中心とした運用改善」を実現するためのmd-kumihanというツールはできたので、次は自分のチームで勝手に実践だ。