ATL の伊藤です。この度、吉村と二人で「ドキュメント作成システム構築ガイド」という本を執筆しました。読者の対象は、本の執筆を職業としている人というよりは、エンジニアです。エンジニアが自分の作品をつたえるドキュメント(仕様書、マニュアルなど)を効率的に作成する施作について紹介しています。また校正が必要な社内文書の作成、管理にも利用できる内容となっています。社内ドキュメントの品質管理に悩んでいる方は是非手に取ってください。本は3月25日に出版される予定です。

内容、概要

本書は文書作成で役立つトピックをいくつか扱っています。以下各トピックの紹介です。

  • バージョン管理システム
    ソフトウェアエンジニアはバージョン管理システムを利用して開発をおこないいます。バージョン管理システムを導入すると、問題箇所の同定や問題の再現に利用できます。本書ではバージョン管理システムの一つ、Git とそのホスティングサービス GitHub を利用したドキュメント執筆の流れを具体例を通して解説します。

  • マークアップ言語と、ドキュメント生成ツール
    これまで HTML や TeX のようなマークアップ言語が多数提案されてきました。本書は Markdown と AsciiDoc というシンプルなマークアップ言語を紹介します。特に AsciiDoc については、海外で大きな流れになっているにもかかわらず、日本語ドキュメントは整備されていません。本書では AsiiDoc の記法の解説に加え、出力フォーマット(PDF、HTML)に変換する際の見栄えを指定する方法についても詳しく解説します(Asciidoctor)。

  • ドキュメント検査ツール
    ドキュメントを複数人数で執筆すると、利用する専門用語や句読点などが揃わないという問題が起こります。そこで本書ではドキュメント検査ツール、RedPen を利用して自動でドキュメントの問題を検知する方法について紹介します。RedPen はマークアップ言語(AsciiDoc、Markdown等)に対応しているので、製品マニュアルや社内文書など、より専門的なドキュメントの自動検査に利用できます。

  • 継続的インテグレーション
    ソフトウェア開発では、最終成果物に問題がないかを継続的に検査する習慣(継続的インテグレーション)が広まっています。本書では継続的インテグレーションをサポートするサービス Travis をドキュメント作成に取り入れる方法について紹介します。

各トピックの解説に利用したサンプルサポートページにありますので参考にしてください。

書き終わった感想

以下、本書を書き終わった後の感想を以下つらつらと。

  • 感謝
    本書の扱うトピックは見栄えのするアルゴリズムでもなければ、流行りの技術でもありません。それでも本書の出版にゴーサインを出していただいた技術評論社に感謝しています。

  • 社内文書
    書き終わったあと、本書を引用していただいている Qiita の記事 を発見しました。内容は、「手順書というドキュメント作成に、表計算ソフトを使うのはやめたほうがよい」というものです。本を書いているときには意識していませんでしたが、私も社内の技術文書を表計算ソフトでやりとりするのは非効率だと考えています。近い将来、手順書を含む技術ドキュメントが表計算ソフトから、軽量マークアップ言語とバージョン管理システムに移行して欲しいですし、本書がその一助となれば嬉しいです。

  • 自然言語
    ソフトウェアエンジニアであれば得意、不得意を含め十個以上のプログラミング言語を習得しています。それでも利用するプログラミング言語やイディオムは時代ととともに変化してしまいます。自然言語はソフトウェアエンジニアが離れられない言語の一つです。さらに自身の作品を他者に引き継ぐ際には、必須の言語でもあります。私は自然言語の執筆に関するノウハウはもう少し注目されてもいいかなと感じています。また、本書で取り上げたトピックはまだまだ改善の余地が大きいです。今後、執筆環境を改善するための本が出てくるのを読者として楽しみにしています。

本書の原稿

本書の執筆は GitHub のリポジトリを利用しました。執筆を通して GitHub の課題(Issue)の形で技術評論社の高屋さんより多くの助言をもらいました。いただいたアドバイスの幾つかは RedPen で機能を作って本書の自動検査に利用しました。

たとえば、高屋さんより漢字の連続は読みにくいというコメントをいただきました。以下はコメントをいただいてから機能(long_kanji_chain.js)を作るまでの様子です。

Screen Shot 2016-03-23 at 14.02.10

作成した機能を含む、本書のソースファイルを一部ですが公開します。是非参考にしてください。また、次にリリースする RedPen v1.6 は今回本書を執筆するときに使用した機能をサポートする予定です。

TAGS: