組み込み組合ぺんぺん草

technical notes...だったらいいな

感想「ドキュメント作成システム構築ガイド」

Overview

ドキュメントに纏わる作業のシステム化にあたり、必要な以下のツールの使用方法を解説した本です。

ツール名 用途
Git ドキュメントのバージョン管理
AsciiDoc、Markdown ドキュメントのフォーマット
RedPen ドキュメントチェック
Asciidoctor ドキュメント生成、変換
Travis 継続的インテグレーション支援ツール

Details

Index

第1部 モダンなドキュメント作成
  第1章 ドキュメンテーション入門
  第2章 利用するツールの準備
  第3章 Markdownによるシンプルなドキュメントの作成
  第4章 GitHubによるドキュメントの管理
  第5章 RedPenによるドキュメントの自動チェック
第2部 本格的なドキュメントの作成
  第6章 AsciiDocによるドキュメントの作成
  第7章 Asciidoctorによる出力フォーマットへの変換
  第8章 Asciidoctorによるスタイルの調整
  第9章 ドキュメント作成システムの構築
Appendix1 AsciidoctorのHTMLスタイル設定

Review

何か製品を開発した際、ドキュメントは不可欠です。ドキュメントの品質が高ければ、ユーザは製品をより理解することができます。そしてその結果、製品が広まることもあると思います。

ここで、小規模な開発であれば、ドキュメントの作成は一人でもなんとかなるでしょう。しかし大規模な開発であれば、ドキュメントの執筆も複数人で行うことになります。その場合、ドキュメント内で用いられる語句などの全体的な統一が必要となります。

また開発の規模のいかんにかかわらず、製品のアップデートに伴いドキュメントの更新が必要となります。製品の最初のリリース時は、ドキュメント作成にまとまったを割いて、且つそれなりのモチベーションをもって行われると思います。しかし製品のアップデート、しかもバグフィックスだったりすると、もう億劫になりがちです。しかもよくあるパターンとして、ドキュメント作業は最後の最後に手をつけ、時間に余裕があるとは言えない状況であることが多いのではないでしょうか?

そんな中でもドキュメントの品質を維持するために、本書ではドキュメント作成システムの構築をすすめます。ドキュメント作成システムは、バージョン管理ツールやドキュメント検査ツール、継続的インテグレーション支援ツールなどから構成されます。 一度システムを構成してしまえば、億劫なドキュメント更新の心理的敷居も多少は下がりますし、コード修正とドキュメント更新をセットで行うことも容易になるかと思います。

なお、継続的インテグレーションについては本書中で以下の書籍が推奨されています。

本書の中で主に使用しているツールについて、どの程度触れられているかは、以下の通りです。

  • Git
    • ご存知バージョン管理ツールです
    • インストールから設定まで触れています
    • GitHubの使用方法も触れています
  • Markdown
    • ドキュメント作成の際に用いる言語です。メジャーですね
    • 基本的な書式について一通り触れています
  • AsciiDoc
    • Markdown同様ドキュメント作成に用いる言語です
    • Markdownよりマイナーではありますが、Markdownよりも多機能で痒いところに手が届きます
  • Asciidoctor
    • AsciiDocで記述されたドキュメント用の文書生成ツールです
    • HTMLやPDFなどに変換してくれます
    • インストールから使用方法まで触れています
  • RedPen
    • 文書検査ツールです
    • 文体や用語のブレを検出してくれます
    • また細かい設定も可能なので、設定を積み上げていくことで、より精度をあげていくことができます
    • インストールから使用方法まで触れています
  • Travis
    • 継続的インテグレーション支援ツールです。Jenkinsは導入や維持が大変ですしね(ただし非公開で使用する場合は有償です)
    • ログインから設定、push後実際にテストが行われるところまで触れています

本書では上述の通り、ツールのインストールや設定、使用例などを記述しています。またよくあるドキュメント作成や修正の流れを説明しています。よってドキュメントの書き方などを説明しているものではありません。個々のツールのインストール方法などはWeb上で調べることも可能ですが、ドキュメント作成「システム」としてまとめられているので、様々なツールの組み合わせに悩むことなく始めることができます。現状のドキュメント作業にかかる問題解消のために試してみる場合の導入として最適だと思います。