ドキュメント作成システム構築ガイド を読み終えたので、その感想です。GitHubとCIサービスの組み合わせ方、gitやmarkdownの初歩的な使い方も丁寧に書かれているので、意外と新人向きの書籍かもしれません。

発売前に、エクセルで手順書を作るのはきっとやめた方がいいという自分の投稿に、その解決策としてCIに沿ったライティングの情報を追加したのですが、それが著者のお一人の目に留まったらしく、なんだか恐縮です。

概要

ソースコードの品質を高めるために、継続的インテグレーション(CI)が導入されてきたように、ドキュメントに対してもそれをやろうというものです。そのために

• バージョン管理システム(Git)
• Gitで差分が見やすい軽量マークアップ言語(markdown,asciidocなど)
• 文章を校正するためのツール(RedPen,textlintなど)
• PDFやHTMLなどに出力するためのツール(Asciidoctor)
• CIサービス(TravisCI,CircleCIなど)

を導入します。

1部では、gitの使い方、markdownの記法、GitHubでのプルリクエストとレビューのやり方、RedPenの使い方をとりあげています。2部では、より表現力のあるAsciidocの使い方と、それをTravisCIでRedPenでのチェック、htmlとpdfの出力を自動化するやり方をとりあげています。

ソースコードでのCI

Javaのプロジェクトで、次のようなCircleCIを使って、次のようなものを作ったことがあります。

• GitHubでプルリクエスト作成+コードレビュー
• JUnitでテストコード実行
• findbugsで静的解析
• テストのカバレッジなどのレポート作成

コードの静的解析とドキュメントの校正が、同じ立ち位置といえます。プロジェクトにはよっては、jarなどの実行ファイルの作成をすることもあり、それがドキュメントで言えば指定のフォーマットでの出力に対応しているでしょう。

まとめ

CIを使ったソフトウェア開発を経験したことがあれば、ドキュメントにどう適用するかはイメージしやすいと思います。そのためのツールの一例を知るにはこの本はとっつきやすいでしょう。

また、そもそもCIの経験がない人にとっては、仕組み作りの手本にもなるのでおすすめです。どういうものが自動化できるかを知れば、自分の仕事でどこかが自動化したいのか、できるのかというのが見えてくると思います。

一昔前であれば、ドキュメントならwordやexcelで作るものだったかもしれませんが、markdownやasciidocなどの選択肢がでてきているので、そういったやり方にとらわれる必要はないでしょう。できそうなところから、markdownでドキュメントをつくったり、gitのバージョン管理を組み合わせてみたりすると、これから先を生き抜くための基礎スキルが身につくのでは。

参考サイト