『読みやすい技術書を書く技術』という本を技術書典7で頒布します #技術書典

『読みやすい技術書を書く技術』とは

読みやすい技術書を書く技術』では、「書く」というプロセスにソフトウェア開発の考え方を導入します。 この本では読みやすい文章を執筆するための「環境構築技法」にフォーカスし、継続的に文章を校正する仕組みを整えます。 ちなみに「文章を読みやすくする文章術」については一切出てきません

対象読者は「読みやすい文章を書きたいエンジニア」です。 技術書のような長い文章を書く人には、特に役立ちます。 また、技術ドキュメントやブログを書く人にも有益です。

techbookfest.org

なにが書かれているか

読みやすい技術書を書く技術」では校正ツールprhRedPentextlintの使い方を学びます。 さらにこれらのツールをCircleCIに組み込み、校正ツールを実行するCI環境を構築します。 最終的には次のようなワークフローの継続的インテグレーションを実現します。

f:id:tmknom:20190901235628p:plain

CircleCIにはreviewdogを導入し、GitHubに校正ツールの実行結果を通知します。 これにより次のような通知が、GitHubへ自動的に飛んでくるようになります。 なお、わりと容赦なく怒られますw

f:id:tmknom:20190901235310p:plain

f:id:tmknom:20190901235334p:plain

さらにRe:VIEWを前提にPDFをCircleCIで自動生成します。 GitHubに原稿をプッシュすると、CircleCIがPDFのリンクをGitHubへ通知するので、校正がとても捗るようになります。

f:id:tmknom:20190901235408p:plain

以上のようなことが「読みやすい技術書を書く技術」を読めば、誰でもできるようになります。 技術書を書いている人には、わりと最高な感じの環境ですよ!

頒布情報

「読みやすい技術書を書く技術」は『【お20C】KOS-MOS』にて頒布します。 頒布数の参考にしたいので、よろしければサークルチェックをお願いします。

techbookfest.org

なお、技術書典7は2019/09/22 (日) 11:00〜17:00の日程で開催されます。 場所は「池袋サンシャインシティ 展示ホールC/D(文化会館ビル2/3F)」です。

目次(案)

頒布時に変更されてる可能性もありますが、現時点での目次案は次のとおりです。

 1章 出ない神本より出るクソ本
   1.1 完璧を目指すよりまず終わらせろ
   1.2 読者のことを考える
   1.3 校正ツール
   1.4 継続的インテグレーション
 2章 Docker
   2.1 Dockerとは
   2.2 Dockerのセットアップ
      2.2.1 Docker Hubのアカウント登録
      2.2.2 Dockerのインストール
   2.3 Dockerの使い方
      2.3.1 Dockerコンテナの起動
      2.3.2 Dockerイメージのビルド
      2.3.3 Dockerイメージのプッシュ
 3章 Re:VIEW
   3.1 書籍執筆ツール
      3.1.1 Word
      3.1.2 InDesign
      3.1.3 Markdown
   3.2 Re:VIEWとは
      3.2.1 Re:VIEWの利点
      3.2.2 Re:VIEWテンプレート
      3.2.3 Re:VIEWの情報源
   3.3 Re:VIEWのセットアップ
      3.3.1 テンプレートの取得
      3.3.2 Re:VIEWのインストール
   3.4 Re:VIEWの使い方
      3.4.1 プリプロセッサ
      3.4.2 PDFの生成
      3.4.3 EPUBの生成
 4章 prh
   4.1 prhとは
   4.2 prhのDockerfile
   4.3 prhの使い方
      4.3.1 prh.ymlの生成
      4.3.2 prhコマンドの実行
      4.3.3 prh.ymlの指定
      4.3.4 prhによるエラーの自動修正
      4.3.5 prhの終了ステータス
   4.4 prhの設定
      4.4.1 英単語の表記ゆれ
      4.4.2 表現の統一
      4.4.3 タイポの抑制
      4.4.4 正規表現によるルール定義
      4.4.5 ルール定義のテスト
      4.4.6 設定ファイルのインポート
   4.5 prhのエラーを抑制する
 5章 RedPen
   5.1 RedPenとは
   5.2 RedPenのDockerfile
   5.3 RedPenの使い方
      5.3.1 redpenコマンドの実行
      5.3.2 ファイル形式の指定
      5.3.3 RedPenの出力フォーマットの変更
      5.3.4 RedPenの終了ステータス
   5.4 RedPenの設定
      5.4.1 redpen-conf.xmlの定義
      5.4.2 RedPenの設定のカスタマイズ
      5.4.3 設定ファイルの育て方
   5.5 RedPenの主要な設定項目
      5.5.1 CommaNumber
      5.5.2 JapaneseStyle
      5.5.3 InvalidExpression
      5.5.4 JapaneseNumberExpression
      5.5.5 JapaneseJoyoKanji
      5.5.6 LongKanjiChain
      5.5.7 SentenceLength
      5.5.8 SectionLength
   5.6 RedPenの無効化すべき設定
      5.6.1 SpaceBetweenAlphabeticalWord
      5.6.2 KatakanaEndHyphen
   5.7 RedPenのエラーを抑制する
 6章 textlint
   6.1 textlintとは
   6.2 textlintのDockerfile
   6.3 textlintの使い方
      6.3.1 textlintコマンドの実行
      6.3.2 textlintの出力フォーマットの変更
      6.3.3 textlintによるエラーの自動修正
      6.3.4 textlintの終了ステータス
   6.4 textlintの設定
      6.4.1 .textlintrcの定義
      6.4.2 .textlintrcの指定
      6.4.3 textlintの設定のカスタマイズ
   6.5 textlintの主要な設定項目
      6.5.1 no-doubled-joshi
      6.5.2 no-doubled-conjunction
      6.5.3 ja-no-weak-phrase
      6.5.4 ja-no-redundant-expression
   6.6 RedPenと重複する設定項目
      6.6.1 max-ten
      6.6.2 max-kanji-continuous-len
      6.6.3 no-mix-dearu-desumasu
      6.6.4 sentence-length
   6.7 textlintのエラーを抑制する
 7章 CircleCI
   7.1 CircleCIとは
   7.2 CircleCIのセットアップ
      7.2.1 CircleCIのアカウント登録
      7.2.2 CircleCIプロジェクトの作成
   7.3 CircleCIの設定
      7.3.1 バージョン
      7.3.2 ワークフロー
      7.3.3 ジョブ
   7.4 校正ツールの組み込み
      7.4.1 校正ツールのDockerイメージのプッシュ
      7.4.2 ワークフローへ校正ツールの組み込み
      7.4.3 校正ツールスクリプト
      7.4.4 prhジョブ
      7.4.5 redpenジョブ
      7.4.6 textlintジョブ
   7.5 校正ツール組み込み後のCircleCIの設定
 8章 reviewdog
   8.1 reviewdogとは
   8.2 reviewdogの使い方
      8.2.1 reviewdogの入力データ
      8.2.2 reviewdogの実行
      8.2.3 reviewdogの入力フォーマット
   8.3 CircleCIとGitHubの連携
      8.3.1 GitHubトークンの生成
      8.3.2 CircleCIの環境変数の設定
   8.4 reviewdogのCircleCIへの組み込み
      8.4.1 コマンドの追加
      8.4.2 校正ツール実行ジョブの修正
      8.4.3 prhスクリプトへの組み込み
      8.4.4 redpenスクリプトへの組み込み
      8.4.5 textlintスクリプトへの組み込み
   8.5 reviewdog組み込み後のCircleCIの設定
 9章 PDFの自動生成
   9.1 CircleCIによるPDFの自動生成
      9.1.1 ワークフローへgenerateジョブの組み込み
      9.1.2 generateジョブの定義
      9.1.3 generateスクリプトの実装
   9.2 リンクの通知
      9.2.1 CircleCIトークンの発行
      9.2.2 ワークフローへnotifyジョブの組み込み
      9.2.3 notifyジョブの定義
      9.2.4 notifyスクリプトの実装
   9.3 PDF自動生成組み込み後のCircleCIの設定
10章 限界、そしてその先へ
   10.1 ツールの限界
   10.2 あなたの文章は伝わりますか
   10.3 興味のないことについて書こうと思うな

書いてる人

アーキテクチャ設計とドメイン駆動設計が得意なSREです。 著書には同人誌「Pragmatic Terraform on AWS」があります。 この本は技術書典とBOOTHで累計1,500部以上を販売しました。 下記は読者の方に書いていただいた書評記事です。(みなさん、ありがとうございます!

また本のクオリティの参考に、昔書いたQiitaの記事のリンク貼っておきます。 これぐらいのクオリティになると思うので、参考にしていただければ幸いです。

おわりに

ではではみなさん、当日会場でお会いしましょう。 来れない方は、BOOTHで電子書籍出すつもりなので、そちらをよろしくおねがいします!

techbookfest.org