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

書籍の概要

この本の概要

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

こんな方におすすめ

  • Webサービス開発者,技術文書を公開したいと考えているエンジニア

この書籍に関連する記事があります!

エンジニアにとっての技術文書
エンジニアが成果物を作るたびに,成果物を解説する技術文書が必要になります。

目次

第1部 モダンなドキュメント作成
第1章 ドキュメンテーション入門

  • 1.1 ドキュメントの種類
  • 1.2 ドキュメントの品質
  • 1.3 オープンソース化するドキュメント
  • 1.4 ドキュメントを作成する際の注意点
  • 1.5 規約に基づいたドキュメント作成
  • 1.6 共同作業による効率アップと問題点
  • 1.7 継続的インテグレーション
  • 1.8 ドキュメント作成でも継続的インテグレーション
  • 1.9 まとめ

第2章 利用するツールの準備

  • 2.1 利用するツールの概要
  • 2.2 バージョン管理システム
  • 2.3 ドキュメント検査ツール
  • 2.4 継続的インテグレーションツール
  • 2.5 エディタ
  • 2.6 まとめ

第3章 Markdownによるシンプルなドキュメントの作成

  • 3.1 Markdownの特徴
  • 3.2 Markdown の記法
  • 3.3 Markdown記法のサンプル
  • 3.4 Markdownの限界
  • 3.5 まとめ

第4章 GitHubによるドキュメントの管理

  • 4.1 Gitを利用したドキュメント作成の流れ
  • 4.2 GitHubでの公開
  • 4.3 GitHubを利用したドキュメントの管理
  • 4.4 コンフリクトへの対応
  • 4.5 リリース管理とタグ
  • 4.6 まとめ

第5章 RedPenによるドキュメントの自動チェック

  • 5.1 RedPenの特徴
  • 5.2 RedPenを使ってみる
  • 5.3 RedPenの設定
  • 5.4 RedPenが提供する機能
  • 5.5 RedPenが提供するコマンド
  • 5.6 RedPenをサーバとして利用する
  • 5.7 RedPenの機能を作成する
  • 5.8 まとめ

第2部 本格的なドキュメントの作成
第6章 AsciiDocによるドキュメントの作成

  • 6.1 AsciiDocの文法
  • 6.2 AsciiDocのサンプル
  • 6.3 まとめ

第7章 Asciidoctorによる出力フォーマットへの変換

  • 7.1 Asciidoctorを利用する準備
  • 7.2 HTMLへの変換
  • 7.3 PDFへの変換
  • 7.4 EPUBへの変換
  • 7.5 Asciidoctor以外のドキュメント生成ツール
  • 7.6 まとめ

第8章 Asciidoctorによるスタイルの調整

  • 8.1 スタイルファイル
  • 8.2 設定項目名の構造
  • 8.3 設定値の展開・演算・組込み関数
  • 8.4 スタイルファイルの全体像
  • 8.5 書体の指定
  • 8.6 外観の指定
  • 8.7 表紙の指定
  • 8.8 ヘッダ,フッタの指定
  • 8.9 アトリビュート
  • 8.10 アトリビュートをスタイルファイルで利用する
  • 8.11 まとめ

第9章 ドキュメント作成システムの構築

  • 9.1 ドキュメント作成システムの構成
  • 9.2 ドキュメント作成システム構築までの流れ
  • 9.3 ドキュメント作成システムにおける編集からマージまでの流れ
  • 9.4 課題の管理
  • 9.5 編集処理の事例
  • 9.6 設定の詳細
  • 9.7 まとめ

Appendix1 AsciidoctorのHTMLスタイル設定

  • A1.1 スタイルファイル編集の準備
  • A1.2 スタイルファイルを生成する
  • A1.3 スタイルファイル設定
  • A1.4 まとめ