ドキュメント作成システム構築ガイドを読んだ

　気になっていた『ドキュメント作成システム構築ガイド』が、Kindle版になっていたので読みました。最近の私の関心テーマおよび課題とマッチしていたので、なかなか興味深かったです。

本書の内容

　本書の概要は、Amazonさんには下記のように公開されています。

アプリケーションの開発手順，製品のユーザマニュアルなど，ドキュメントの多くはエンジニアによって作成されています。ドキュメントの品質が低い場合，読み手が誰であっても内容の理解に時間がかかります。ドキュメントは簡潔で内容を正確に伝えるものでなければなりません。エンジニアにとってドキュメント作成は避けて通れません。いまやドキュメント作成はコーディングと同様にエンジニアに必要な技術なのです。本書は，ソフトウェア開発の技法に基づいてドキュメント作成を支援するシステムを構築します。このシステムではGitを用いたバージョン管理，GitHubによる共同編集，RedPenによる品質チェック，CIツールによる継続的改善などを利用します。応用としてAsciidoctorによるドキュメントのスタイル調整について解説します。Webでの公開に耐える品質はもちろん，技術文書の電子出版においても役立つ内容となっています。。

　主に技術文章を公開する人向けとあるのですが、実は対象とする読者層は多いのではないでしょうか。技術文章の範囲には、設計書等も含まれるからです。どこの現場でもあると思いますが、設計書の記述・保守については悩まされる問題だからです。

私の目的

　設計書も対象と言ったものの、私自身はその辺りにフォーカスして読んでいません。主に著書の執筆環境の改善です。またどちらかと言うと、今後挑戦しようと思う Amazon Kindle ダイレクト・パブリッシング（KDP）の為の環境作りです。また本書自体も、論文等の公開文章を前提としていると思います。

　現在、私は下記のような流れで書いています。

1. Markdownで記述
2. GitHubで管理
3. Markdownの原稿を元に確認
4. DTP出稿
5. 校正
6. 出版

　1〜3の部分については、全く問題がないです。4と5の部分が問題ありです。

　まずDTP出稿です。DTPとはDesktop publishingの略で、原稿と図表を組み合わせて印刷可能な状態にすることです。一般的に書籍のページとして見る状態にするというイメージですね。ここの部分については、現在大手の出版社とやっていることもありお任せ状態です。しかしKDPをしようと思うと、この工程を自分で行う必要があります。現状のMarkDownからの変換では、表現力・調整力不足で何らか対策が必要です。
　次に校正です。校正というのは、確認と修正です。DTPを元に確認して修正するのですが、この反映をどこにするのかが問題になります。基本はDTP済みのものに対して修正することになるのですが、そうすると元の原稿との乖離が出てくる。元原稿も修正するとなると二重管理になるという課題があります。

　この課題を解決するには、原稿からDTP化するシステムを作るしかないかなと考えています。過去にも幾つか模索したことはありますが、MarkDownの表現力では現状は難しいという結論です。そこでSphinx+reStructuredText(reST)かなと思っていました。

今回の知見

　本書で中心的に取り上げられたAsciiDoc+Asciidoctorも良さ気に見えました。Sphinx+reSTと比較してどちらを採用するか考えてみます。あと文章のフォーマットチェック（赤ペン先生？）であるRedPenは良さそうですね。JavaScript版もあるみたいなので、API化して他システムと連携することも出来そうです。これは試してみます。そして、夢のKindleダイレクト・パブリッシングで、自費出版です！！

ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによるモダンライティング]

作者: 伊藤敬彦,吉村孝広
出版社/メーカー: 技術評論社
発売日: 2016/03/25
メディア: Kindle版
この商品を含むブログを見る

以下、目次です。

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