HN 日本語サマリー

← 一覧へ戻る
プログラミング

私の本を過剰に設計してしまった方法

How I Over-Engineered My Book (ben.balter.com)

18 pointsby benbalter10 コメント

要約

著者は、自身の書籍執筆プロセスにおいて、開発者が日常的に使用するツール(Git、Markdown、CIパイプライン)を適用し、リンターや自動テストを含む高度な自動化システムを構築しました。このシステムは、文法チェックから内容の矛盾検出まで、約5,500もの自動チェックを実行し、執筆の品質と効率を極限まで高めることを目的としています。

全文翻訳

いかにして私は自分の本を過剰設計したか

私の本には、私が「オープンソース」をハイフンでつないでいると文句を言うリンターが搭載されています[1]。それは、一連の自動チェックを実行し、各git pushごとに全フォーマットを再構築し、私がすでに辞めたはずの仕事について言及しただけでビルドを失敗させます。本のためにです。たった一人の人間が書いた本のために。

意図してこうなったわけではありません。ほとんどの人はWordやGoogle Docsで執筆プロジェクトを開始しますが、私も同じ道を歩み始めました。専用の執筆ツールも試しましたが、どのツールも開発者として日々使っているものに劣っていると感じました。私は「唯一合理的な」選択をし、それらをすべて捨て、Git、Markdown、そしてCIビルドパイプラインで本全体を書くことにしました。もし私がどのように自宅ネットワークを過剰設計したか(2回)を読んだことがあるなら、これに驚くことはないでしょう。

何十年もウェブサイトを作ってきたので、その移行は容易でした。ウェブサイトを構築するのと同じツールで本を構築できるのです。標準的なWord文書を魔法のように完全な本に変えるための、土壇場のマジックトリックは必要ありませんでした。いくつか間違いもありましたが[2]、最終的に、私はOpen and Asyncを他の方法で書くことはなかったでしょう。

コンテンツ

当然のことながら、コンテンツ自体はGitリポジトリ内のMarkdownファイルとして保存されました。結局のところ、それが私のほとんどの時間を費やす場所だからです。私はVS Codeを使用し、いくつかのプローズ拡張機能(下記参照)を導入しました。各章は独自のMarkdownファイルであり、単一のindex.ymlファイルで順序が定義されていたため、章の並べ替えや追加が容易でした。

実際には、私はこの本のほとんどをiPadで執筆しました(ブラウザタブでのCodespaces、Bluetoothキーボード、しばしばデスクから離れた夜や週末に)。Gitリポジトリは、どこで開いてもすべてを同期させてくれました。私は言葉に集中でき、悪いアイデアはgit revert一つで消去できました。

さらに、IDE内で様々なプローズリンターからリアルタイムで執筆に関するフィードバックを得ることができました。これは、ESLintやPrettierからコードに関するリアルタイムフィードバックを得るのと同じです。

テスト

コンテンツをコードとして扱うなら、次の論理的なステップ(そして「合理的」が静かに姿を消した地点)は、自動テストの設定でした。コードをテストするのと同じようにプローズをテストすることは、私が長年主張してきたことです。今回はそれを不条理な極限まで推し進めました。これは2つの方法で行いました:リアルタイム、そしてプッシュ時(CI)です。

リアルタイム

ローカルでは、入力中にいくつかのVS Code拡張機能を実行し、すべてリアルタイムでフィードバックを提供してくれました。具体的には以下の通りです。

  • Markdownlint: Markdownの構文とフォーマットの一貫性
  • Harper[3]: 文法と単語の選択、完全にオンデバイスで実行
  • LanguageTool: 文法、句読点、スタイル[4]
  • Vale: 私自身のハウススタイルルールと禁止用語
  • Alex: 不適切または排他的な表現
  • Write-good: 受動態、曖昧な言葉、決まり文句などの弱い散文

これら6つすべてがCIでも実行されました(AlexとWrite-goodはそこでValeに統合されました。詳細は下記)。これらを組み合わせることで、完全な文法エンジン上で数百のキュレーションされたスタイルルールがレイヤー化され、すべてがリアルタイムで私の間違いをアンダーライン表示しました。これは、コードのエラーを赤線で示すのと同じです。

プッシュごと

CIでこれらのオープンソースリンターを実行する(一部はビルドをブロックする)ことに加えて、独自のカスタムテストスイートを構築しました。コンテンツバリデーター、Vitestスイート、PlaywrightスペックからなるスタンドアロンNodeスクリプトです。バリデーターが面白い部分です。それぞれ数行のコードでMarkdownを読み取り、ファイルと行番号を指し示すエラーを発生させます。私のお気に入りは、私はもうGitHubで働いていないので、私がまだ働いていると主張する文章はビルドを失敗させるというものです。

// My time at GitHub has to read as past tense — present-tense// employment claims about it fail the build.function validateGitHubTense(files) {  const patterns = [    // "is/are ... at GitHub" — a current-employment claim    /\b(is|are)\b[^.!?\n]{1,80}?\bat GitHub\b/i,    // "works/leads/runs at GitHub" — current-employment activity    /\b(works?|leads?|runs?|manages?|directs?)\s+(at|for)\s+GitHub\b/i,  ];  return flagLinesMatching(files, patterns);} 

そのバリデーターは、私が一度間違えたから存在します。それがパターン全体です。一度エラーが私をすり抜けたとき、私はその文だけを修正したのではありませんでした。二度と目視で捕まえる必要がないようにルールを書きました。プローズにとって、それは家畜でありペットではないのです。各章を手で世話するのではなく、ポリシーで群れ全体を管理するのです。一度捕らえられた間違いは、すべての章をスキャンし、それが再び現れた場合にビルドを失敗させるチェックになります。それは約30個のうちの1つです。私が誇りに思っている他のものには以下があります。

  • validateOpenSourceHyphenation: 「open source」は動詞ではなく名詞であり、ハイフンでつながれることはありません。
  • validateHypotheticalHooks: 段落の冒頭にある、定型的なAIが生成したようなオープナー(「Picture this…」、「Imagine…」、「Consider a…」)。
  • validateSentenceStarters: 同じ単語で始まる文が3つ以上続く場合。
  • validateNoBareUrlLinkText: 表示テキストが単なる生のURLであるリンクがないこと。
  • validateCalloutBalance: 本はマネージャーと個人貢献者の両方に語りかけるため、「マネージャー向け」のコールアウトには「IC向け」の対応するものが近くにある必要があります。
  • validateCrossReferences: すべての[テキスト](#anchor)クロスリファレンスが実際のヘッダーに解決されること。

…その他、スモールキャップ、emダッシュ、二重単語、enダッシュの範囲、TL;DRの長さ、その他私が名前を付けられるあらゆる癖に対応する数十個のものがあります[5]。

これらのうちの1つが私を捕らえました。validateHypotheticalHooksが、私が自分で書いたと確信していた段落の冒頭をフラグ付けしました。そして、実際に書いたのです。しかし、冷静に読み返すと、ゴーストライターが書いたように聞こえました。生成されたテキストを読みすぎたためにそのリズムを吸収し、何も生成していない流暢な模倣を作り出していました。リンターは良いプローズと悪いプローズを区別できません。しかし、それがフラグを立てられるのは、あなたが考えていないときに手を伸ばすパターンであり、それはまさに自分のドラフトでは見えないものです。私がeslintを使い続けているのと同じ理由です。それは良いコードと悪いコードを区別できませんが、あなたの目がすぐに通り過ぎてしまう自動操縦のミスを捕らえてくれます。

全体として、CIスイートは約70個のテストファイルで2,204個のテストケースと約3,900個のexpect()アサーションを実行し、さらに上記のバリデーターから各章あたり約1,600個の構造チェックを実行しました。

監査

リンターは間違いを検出しましたが、本が自己言及しているかどうか、あるいは章が優れているかどうかを教えてくれるわけではありませんでした。そのため、私は第二層のツールを構築しました。それは、プローズをチェックするだけでなく、評価する監査ツールです。しかし、それらが決してしなかったことの一つは、執筆することです。すべての単語は私のものです。これらのツールは最後の読者であり、私が気づけなくなったものを見つけてくれます。

重複検出

本を何度も読み返すうちに、章をまたいで同じアイデアを繰り返していると確信しました。証拠が欲しかったのです。推測ではなく。そこで、3層の重複検出を構築しました。それぞれが前の層が見逃したものを見つけます。

  • jscpd: トークンレベルのコピー&ペースト検出。章間で貼り付けた長い逐語的なブロックを検出しますが、それより微妙なものは検出できません[6]。
  • n-gram: index.ymlの各章をトークン化し、Markdown/Pandoc構文を削除し、単語のn-gram(n個の単語のフレーズ)を構築し、複数の章に出現するフレーズ(および「最も繰り返される定型文」ランキング)をフラグ付けします。2つのモードがあります:章間(デフォルト --n)と章内(--scope=intra --n=8)で、章が自己言及している場合。
  • セマンティック: 他の2つができないこと、つまり同じポイントが異なる言葉で言い換えられていることです。オンデマンドのLLM監査で、本全体をモデルにフィードしないように設計されており、3つのパスを実行します。それぞれが小さな単位に対して行われます。
    • 章内: 章ごとに1回の呼び出し:「この章はどこで自己言及しているか?」
    • 章間: 各章のTL;DR全体に対する単一の呼び出しで、概念的に重複する章のマッピングを生成します。1回の呼び出しコストで本全体のスキャンが可能です。
    • 議論: 各章の中心的な主張を1回ずつ抽出し、最後に1回の呼び出しで全章にわたる同じ議論をクラスタリングします。crossが見逃した本文中の議論を検出します。

実際に自分が繰り返していたのでしょうか?この最終パスまでに、2つの機械的な層はクリーンになりましたが、それらはその価値がありました。jscpdとn-gramスキャンはすでにコピー&ペーストと再利用されたフレーズ(ここで二重のモチーフ、あそこで再利用されたTL;DR構造)を検出しており、私はそれぞれを修正しました。

どちらも検出できなかったのは、より微妙な種類のものでした。もはや単語ごとに重複しているものはありませんでしたが、同じポイントが異なる言葉で繰り返されていました。セマンティックパスがそれを検出し、それは正しかったです。私は、オフィスでの習慣をオンラインに移すことは、リモートファーストで働くことと同じではないという同じ議論を、5つの別々の章で行っていました。さらに、51章にわたって166個の小さな自己言及が散らばっていました。私はLLMよりも安価なものには検出されないほど、自分自身をうまく言い換えていました。

私の推測は正しかったのです。再読して目がかすむほどの疲労でも捉えきれなかったものを証明するために、3つの段階的なツールが必要だっただけです。

コンテンツ監査

重複以外にも、第二のツールセットがプローズ自体を評価しました。それらは評価方法によって分割されます。一部は確率的(LLMが章を読み、意見を述べる。実行するたびに結果が変わる可能性がある)であり、一部は決定的(ルールと算術。同じ入力、同じ出力、常に同じ結果)です。

確率的(LLM)監査

「主張」レンズは、他にはないものを早期に捉えました。それは、GitHubの月次全社会議が「各セッションのおよそ半分をライブQ&Aに充てていた」と主張する文で停止しました。それは私が確信していた数字でしたが、間違っていました。実際には3分の1に近く、その割合は年々変動していました。リンターはそれをフラグ付けしません。それはクリーンで自信に満ちたプローズですが、誤りでした。読者が「これは本当に真実か?」と尋ねる場合にのみ検出でき、そうでなければそのまま出荷していたでしょう。

Claimsは、「プローズ監査」テストの20個の単一目的レンズの1つであり、各レンズが1つの狭い質問をするように設計された章ごとのLLM監査ツールです。これにより、モデルは曖昧な「良さそうだ」という回答を避けることができます。--lens=allはすべてのレンズを実行し、--models/--roundsは重複排除されたマルチモデルと自己整合パネルを追加するため、発見された問題は複数のモデル(または複数回の実行)で生き残る必要があります。残りの一部をサンプリングします[7]。

レンズ検出するもの
AI-tells機械生成のように読める表現、私の声ではない
Hookオープニングが実際の作業をしているか、単なる準備運動か
Legal法的または評判上のリスク(名前を挙げる、検証されていない主張)
Dated悪く古くなる可能性のある一時的な参照(「最近」、「今年」)
Global非米国読者を混乱させる慣用句や文化的仮定
Dual-audience章がマネージャーと個人貢献者の両方に役立つかどうか
Promise章が本の中心的な約束を果たしているかどうか

別途、特性分析テストも実施し、説得力とエンゲージメントの特性を各章で採点し、技術的にはクリーンだが平坦なプローズを検出し、人間による再レビューを可能にしました。

決定的監査

これらの監査は、編集ラウンドの後に行われ、本が読書体験として改善されているかを確認しました。章と段落の長さの分布、本全体の読書時間、ハードなEPUBサイズ予算(Kindleは配信時に大きすぎるファイルをペナルティします)、本全体の整合性チェッカー、そして「注意項目」(TL;DRがない章、バランスの取れていないコールアウトなど)がゼロでない場合にビルドを失敗させる--checkモードを持つ統計ダッシュボードです[8]。

これらを組み合わせることで、「本は実際に良くなっているか?」という疑問が、感覚的なものから、ドラフト間で変化を観察できる数値へと変わりました。

[画像: Open and Asyncの執筆ダッシュボード:合計99,651語、読書時間399分、72章、平均章あたり1,384語、マネージャー向けコールアウト103件、IC向けコールアウト102件、プロのヒント123件、異議申し立て62件という概要カードが表示され、下部には「問題なし、すべてのコンテンツ章は良好です!」という緑色のクリアランスが表示されています。]

デザイン

私はデザイナーとは程遠く、電子書籍を出版した経験もありませんでした。それらがどのように機能するのか、多くの電子書籍を読む以外には何も知りませんでした。2つの「アハ体験」が、私の出版に対する考え方を変えました。

  • 電子書籍はトレンチコートを着たウェブサイトである。電子書籍は単なるHTMLとCSSですが、非常に簡略化されたバージョンです[9]。ウェブサイトを作れるなら、電子書籍も作れます。
  • 十分な努力をすれば、印刷書籍もそうなり得ます。CSSにはネイティブで強力な@media printおよび@pageルールがあり、左右のページスタイル、タイトルページ、ページ番号などが含まれます。

インテリアデザインにはTailwind CSSを使用しました。それが本のために作られているからではなく(そうではありません)、私が毎日使っているものだからです。@tailwindcss/typographyは、空白のページから始めるのではなく、タイポグラフィのベースラインを提供してくれました。

1つの注意点:カバーは意図的に人間のデザイナーに依頼しました。誠実さについての本にとって、第一印象は誠実でなければなりませんでした[10]。

見えない漏洩

すべてのフォーマットを1つのスタイルシートからスタイリングすることには、失敗モードがあります。あるフォーマット用のCSSが別のフォーマットに漏れ出すことです。電子書籍リーダーの調整をペーパーバックから遠ざけるために、それぞれを@media not screenにスコープしました。しかし、WeasyPrint(ペーパーバックを描画するHTML/CSSからPDFへのエンジン、詳細は下記)は印刷PDFをprintメディアタイプでレンダリングし、printは仕様通り「not screen」です。そのため、2つの電子書籍リーダーのルールが一致し、静かに本に漏れ込みました。1つはコールアウト段落の行間が狭くなり、もう1つはページをまたいだコールアウトの繰り返しパディングがドロップされました。

どちらも目に見えませんでした。何も壊れているように見えませんでした。しかし、それぞれがすべてのコールアウトから垂直スペースをわずかに削り取り、本は576ページから567ページへとゆっくりと縮小しました。ページ数ゲート(表紙の背表紙を保護するために書かれたもの)が、設計されていなかったCSSバグを捉え、ビルドが赤くなったためにのみ、私はそれを発見しました。1つのスタイルシートから2つのフォーマットを得ることは贈り物ですが、カスケードがどのフォーマットにいるのかを忘れるまでです。修正は、漏洩が勝てないように!importantで明示された、元の値に再ピン留めすることです。

テスト

デザインとレイアウトにもテストスイートがあり、レンダリングされたHTMLに対してPlaywrightで駆動されました。これにより、CSSが何をするはずだったかではなく、実際にレンダリングされるものがチェックされます。2つのカテゴリがあります。

アクセシビリティ(axe-core)

axe-coreエンジンは、ライトモードとダークモードの両方で、WCAG 2.1 AAに対してレンダリングされた本の上で実行されます。クリティカルまたは深刻な違反がないこと、どちらのスキームでもAAカラーコントラスト、すべての画像に代替テキスト、論理的な見出し順序、認識可能なリンクテキスト(「ここをクリック」のようなものがない)、および画面リーダーが正しい発音を選択するための宣言されたlang属性。これはtest:a11yゲートであり、CIではvalidate-playwrightとして強制されます。アクセシビリティは、ここでのサブセクション以上の価値がありました。それには独自のアクセシビリティステートメントがあり、専用のディープダイブが予定されています。

ビジュアル&レイアウト回帰(Playwright)

これらは、実際の計算されたスタイルがデザイン意図と一致することを確認します(静かに壊れて差分には決して現れない詳細)。タイトルページが中央揃えで、より軽量なサブタイトルでレンダリングされること。目次が実際のnavであり、doc-tocロールと機能するリンクを持つこと。各コールアウトタイプが独自の左境界線色と自動生成されたラベルプレフィックスを持つこと。スモールキャップが単なるクラス名ではなく、実際のfont-variant: small-capsであること[12]。

これらはどれも華やかなものではありません。これは、金曜日のCSSリファクタリングで静かに壊れ、読者からメールが来るまで表面化しない種類のものです。

ビルド

クリーンなMarkdownがあり、コンテンツがクリーンであることを保証するテストスイートがありますが、それでも公開可能なフォーマット(EPUB、Kindle、2種類のペーパーバック、およびWeb)に変換する必要があります。このカスタムビルドパイプラインの中核はPandocでした。これはユニバーサルドキュメントコンバーターで、Markdownを読み込み、他のほとんどのものを吐き出すことができます。Pandocをエンジンとして使用しましたが、Pandocだけでは汎用的なドキュメントしか得られません。それを5つのストア対応フォーマットにするには、カスタムツールの山が必要でした。

再現可能なツールチェーン

Pandocは単なるエンジンです。完全なビルドには、PDFを描画するためのWeasyPrint、それを変換するためのGhostscript、そして完全なUnicodeカバレッジのためのNotoフォントの山も必要です。これらはすべて手動でインストールする必要があるネイティブ依存関係の厄介なスタックです。したがって、このすべてはDockerイメージと開発コンテナ内に存在し、正確なレンダラーバージョンにピン留めされています(これはあなたが思うよりも重要な詳細です。下記のページ数ゲートを参照してください)。そのコンテナのおかげで、iPadから本をドラフトできました。重いツールチェーンは私のラップトップではなく、Codespacesで実行されました。

事前処理(Pandocがテキストを見る前)

すべてはソースツリーの一時的なコピーで開始されるため、これらの変換は実際の章に影響を与えません。Pandocを実行する前に、いくつかのスクリプトがそのコピーを処理します。ビルドにコミットSHAをスタンプし、インラインリンクを印刷用の番号付き脚注に変換し(ハイパーリンクは紙では役に立ちませんが、完全なURLを持つ脚注は役立ちます)、フォーマットごとに章を並べ替えて、EPUBは共有可能な引用リンクを取得し、印刷とKindleは代わりにQR共有ページを取得します[13]。

CSSパイプライン

1つのTailwindスタイルシート(src/style.css)がPostCSSを通じてdist/style.cssにコンパイルされるため、スクリーン、印刷、EPUBはすべて同じ真実の源から始まります。各フォーマットは異なるスライスを取ります。strip-page-rules.jsはEPUB用の削減されたスタイルシートを派生させ、KindleとEPUBCheckが問題を起こすCSS Paged-Media機能(@page、target-counter()、oklch()、カスタムプロパティ)を削除します。

Luaフィルター(興味深い部分)

これは私が気に入るとは思わなかった部分です。Pandocはすべてを抽象構文木(AST)に解析し、レンダリング前に小さなLuaスクリプトでその木を書き換えることができます。そのため、フォーマット固有の調整はコード内に存在し、プローズ全体に散らばることはありません。例えば、ノードを削除することは、空のテーブルを返すだけです。

-- strip-comments.lua: 編集用のHTMLコメントを削除し、私のメモが公開された.xhtml内に含まれないようにします。{}を返すことでノードが削除されます。function RawBlock(el)  if is_html_comment(el.format, el.text) then    return {}  endend

残りはそのアイデアのバリエーションです。

  • add-div-titles.lua: コールアウトラベル(「TL;DR: 」、「💡 Pro-Tip: 」、「👔 For managers: 」)とDPUB-ARIAアクセシビリティロールを挿入します。これにより、これらのラベルが各章にハードコードされず、フォーマットごとに異なるものになります。
  • 絵文字、3つの方法で処理: カラー絵文字は画面では問題なくレンダリングされますが、strip-emoji-kindle.luaはKindleセーフなグリフに置き換えます(電子インクには絵文字フォントがありません)。一方、body-emoji-images.luaは印刷PDF用にそれらをインラインのTwemoji画像に変換します。
  • tagline-share-links.lua: EPUBの各「バンパーステッカー」ラインの後に「このアイデアを共有する」パーマリンクを付加します。
暗い箱

絵文字を画像に変換することで、フォント不足の問題が解決され、より微妙な問題が発生しました。TwemojiのPNGは透明ですが、透明ピクセルの下のRGBは濃いスレート色です。レンダラーがアルファチャンネルを尊重すれば見えませんが、そうでない場合は醜いチャコールボックスになります。そして、レンダラーがアルファを尊重するかどうかは、本がどこで開かれたかに完全に依存することが判明しました。

Kindleでは、最初に行った修正は、コールアウトの背景色を各PNGに焼き付け、アルファを完全に削除しました。これはライトモードのPaperwhiteでは完璧に見えましたが、透明度を尊重し、画像の背後にコールアウトのティントをペイントしないKindle for iOSではひどいものでした。そのため、すべての絵文字が濃い色ではなく、色付きの四角形になってしまいました。私は1つの箱を別の箱と交換したのです。現在出荷されているものはアルファをそのまま保持しますが、完全に透明なピクセルのRGBを白に書き換えます。アルファを尊重するレンダラーはクリーンな透明度を得て、それをフラット化するレンダラーは白を得て、白いページでは消えます。

印刷PDFには逆の修正が必要でした。Ghostscriptはペーパーバックを-dNOTRANSPARENCY(テキストを選択可能なベクトルではなく300DPIビットマップとして保持するために必要)でPDF/X-1aに変換し、そのフラグは常にアルファを削除します。そのため、そこでは透明度が敵です。各絵文字は、それが配置されている正確な色(コールアウトのグレー、または本文テキストの白)にアルファなしでフラット化されるため、削除されるものはなく、明らかになる箱もありません。同じバグに逆の修正が必要でした。1つのランタイムはアルファを削除する可能性があり、もう1つは確実に削除します。Pythonスクリプトがビルド時に両方のセットを焼き付けます。

これは世界で最も普通のバグです。私のものはたまたま本の中にありました[14]。

フォーマットごとのレンダリングと後処理

ツリーが変換された後、各フォーマットは独自のパスでレンダリングされ、ペーパーバックが最も長い道のりを歩みます。HTMLとPDFは両方ともPandocでレンダリングされますが、PDFはWeasyPrint(HTML/CSSからPDFへのエンジン)によって描画されるため、ウェブページに使用するのと同じボックスモデルで本全体を組版しました。EPUBは別の方法をとります。PandocはWOFF2フォントサブセットを埋め込み、その後postprocess-epub.jsがそれを再パッケージ化して有効で小さく保ちます。そしてペーパーバックは、他のすべてが停止した後も続行し、GhostscriptでPDF/X-1a:2001(CMYKカラー、埋め込みUSWebCoatedSWOP ICCプロファイル、フラット化された透明度)になります。これは、オンデマンド印刷ディストリビューターであるIngramSparkが必須とする古い印刷標準です。

同じ576ページのゲートがここで二重の役割を果たします。check-pdf-page-count.jsはページ数を固定し、ペーパーバックが576ページからずれた瞬間にビルドを失敗させます。これは、古いページ数が間違ったサイズの表紙の背表紙として出荷されるのを防ぐための安価な保険です。

これは、1つのMarkdownソースから5つの公開可能なファイルになります[15]。これにより、当然の疑問が生じます。それらのどれかが実際に正しいことをどうやって知るのか?

ビルドのテスト

プローズリンターは言葉を正直に保ちます。Vitestスイートのより大きな部分はビルドを正直に保ちます。PandocのアップグレードやCSSの stray line がフォーマットを静かに壊す可能性があり、読者のKindleが間違ったフォントをレンダリングするまで気づかないでしょう。テストは機械をチェックします。各変換が主張する通りに機能すること、そして(圧倒的に最大のクラス)タイポグラフィがスモールキャップ、テーブルの境界線、印刷コントラスト、ダークモード、電子インク絵文字のフォールバックで静かにドリフトしていないことを確認します。それぞれがテストであるのは、それぞれがビルドが正常に見えてもレンダリングが間違っていたのを見た方法だからです。

しかし、単体テストは私のコードが正しいことを証明するだけで、出力が有効であることを証明するわけではありません。そのため、各成果物は、ストア自体が使用するのと同じバリデーターを実行し、拒否はアップロード日ではなく私のラップトップで発生します。すべてのEPUBは、すべてのストアがアップロード時に実行するバリデーターであるEPUBCheckと、電子書籍専用に構築されたアクセシビリティ監査であるAce by DAISYを実行します。ビルドされたHTMLは、リンク切れのためにlycheeによってクロールされ、不正なマークアップが不正な電子書籍になる前にHTMLバリデーターを実行します。

これらはどれも、実行することを覚えておく必要があるものではありません。mainへの各プッシュは、14個の並列CIジョブを開始します。CSSをビルドし、次にEPUB、Kindle EPUB、印刷PDF、PDF/X-1a、HTML、DOCXを並行してビルドし、各成果物が準備でき次第検証します。緑のチェックは、すべてのフォーマットがビルドされ、すべてのゲートを通過したことを意味します。赤いXは、私がまだalt-tabを離れる前に何かがオフであることを意味します。

# build.yml — ほとんど独立したジョブなので、CIはそれらを並列で実行しますjobs:
  build-epub:            # → dist/book.epub
  build-kindle:          # → Kindle固有のEPUB
  build-pdf:             # → 6"×9"ペーパーバックPDF
  build-pdf-ingramspark: # → IngramSpark用のPDF/X-1a
  build-html:            # → Webプレビュー
  validate-epubcheck: { needs: build-epub }
  validate-ace:       { needs: build-epub }
  validate-playwright: { needs: build-html }

[画像: build.ymlのGitHub Actions実行画面。14個の並列ジョブ(lint-and-test、detect-duplicates、build-css、build-epub、build-kindle、build-pdf、build-html、build-docx、およびBuild PDF/X-1a、その後validate-epubcheck、validate-ace、validate-links、validate-html、validate-playwright)がすべて緑色でパスしており、合計所要時間は5分8秒です。]

そして、各ビルドがコミットをタイトルページにスタンプするため、本はソフトウェアのようにバージョン管理されます。私はリリース1.0.1で、タグと変更履歴があり、final_v3_revised_ACTUALLY_FINAL.docxのようなファイルの墓場はありません。タイポの修正はポイントリリースです。

出版

これほど多くの自動化にもかかわらず、実際の出版はほとんどクリック操作です。本番環境へのgit pushはありません。各ストア(AmazonのKDP、書店・図書館向けのIngramSpark、Apple BooksおよびKobo向けのDraft2Digital)では、Webダッシュボードにログインし、EPUBと印刷PDFを手動でアップロードし、同じメタデータ(タイトル、説明、BISACカテゴリ、キーワード、価格)を毎回少し異なるフォームに再入力する必要があります。私のパイプラインは完璧な成果物をビルドし、その後2009年のようにアップロードします。

その部分でさえ、いくつか正直さを保ったことがあります。

  • 私は自分の出版社です。LLCを設立し、独自のISBN(フォーマットごとに1つ)を購入したので、カタログには小売業者の名前が付いた無料のプラットフォームISBNではなく、私が出版社としてリストされます。これにより、それを提供するプラットフォームを通じてのみ公開される無料ISBNに伴うベンダーロックインもなくなります。
  • 排他的ではなく、幅広く。AmazonのKDP Selectはスキップしました。これは、本をAmazonに限定する代わりに少し多く支払われるため、本を一度にどこでも利用できるようにしました。
  • メタデータもバージョン管理されています。説明、カテゴリ、キーワードはリポジトリ(私が差分を取れる単一の真実の源)にあり、それをサポートするチャネルのためにONIXフィードが生成されます。まだWebフォームに手動で貼り付けていますが、少なくともバージョン管理されたファイルから貼り付けています。

今後

ソフトウェアのようにビルドされる本の良い点は、同じ機械がローンチ後も価値を提供し続けることです。

  • 翻訳。コンテンツが構造化されたMarkdownであるため、翻訳は原稿の再入力よりもアプリのローカライズに近いものです。完成した英語の本の翻訳を作成し、クロスリファレンスが壊れないようにすべての見出しIDをピン留めし、用語集を強制して主要な用語を一致させ、結果を逆翻訳して元のものと照合するパイプライン(ブラジルポルトガル語、ラテンアメリカスペイン語、ドイツ語)があります。これは、プローズリンターと同じ「信頼して検証する」という直感ですが、言語を越えたものです[16]。
  • オーディオブック。もし録音するなら、10万語をナレーションに変換することは、誤った発音という全く新しいクラスのバグを開きます。そのため、オーディオブックには独自のQAスイートがあります。生成されたオーディオをテキストに書き起こし、スクリプトと差分を取り、難しい単語の音素をチェックし、発音を監査します。これらはすべて独自のCIワークフローに接続されています。これは私の声に向けられたスナップショットテストです[17]。
  • ツールのリリース。これのほとんどは私の本に固有のものではありません。バリデーター、Luaフィルター、パイプライン全体です。それらをクリーンアップしてオープンソース(ハイフンなしの名詞)として公開したいと考えています。そうすれば、次の人がゼロから構築する必要がなくなります。そして、それがすでに立っているオープンソースプロジェクトなしでは、何も存在しなかったでしょう。本全体は、他人の寛大さの集積です[18]。

結論

1つのMarkdownソース、意見のあるリンター、そして私が間違っているときに叫ぶビルド。これらすべての過剰設計が積み上げたものは次のとおりです。

数字で見る
メトリック数値
単語数約100,000語(約70章とセクションにわたる)
印刷長576ページ(6インチ×9インチ)
公開フォーマット5(出荷しないDOCXを除く)
テスト約70ファイル、2,204ケース、約5,500の自動チェック
プッシュごとのCIジョブ14、並列
スタイルルール500以上の禁止用語をカバーする約300、5,000ルールの文法エンジン上
コミットここに至るまで5,000以上
書籍1冊(率直に言って過剰設計だが、楽しい)

ツールチェーンは本をはるかに超えました。私はこの装置全体を、このブログの15年間のアーカイブに向け、2011年の投稿で、私のリンターがすべてのキーストロークでフラグを立てる、まさに欠けていたアポストロフィである「its clear」を「it's clear」と書いているのを発見しました。何千人もの人々がそれを読みましたが、誰もそれに言及しませんでした。あなたはそれを見つけられません。探しに行かなければならないのです。

そして、転移したのはツールチェーンだけではありませんでした。習慣もそうでした。ここで磨かれた私の直感(一度捕らえられた間違いはそれを永遠に捕らえるルールとして扱う、機械がドラフトしたものは何でも人間をループに入れる、ビルドを真実の源にする)は、すでに私が他のプロジェクト、このサイトを含めて運営する方法に組み込まれています[19]。

小説のために5,500ものテストを書けとは言いません。ほとんどの本にとって、これのほとんどは途方もなく不釣り合いであり、それがポイントです。私はそれを、もう1つのチェック、もう1つのフォーマット、もう1つのバリデーターの限界費用が数分と少しの好奇心だったから行いました。そして、開発者の方法で行ったことで、デスクから離れたiPadから書くことができ、mainが常に出荷可能であることを信頼できました。もしあなたが日々ソフトウェアを出荷しているのであれば、あなたがすでに知っているツールは、あなたが期待する以上にあなたを連れて行ってくれるでしょう。出版業界はワードプロセッサから始まります。私はGitリポジトリから始めました。そして、私は再びそこから始めるでしょう。

あなたなら、あなた自身のツールをそれに向けた場合、何を過剰設計しますか?

脚注

  1. 同僚が初期ドラフトで「open-source」について指摘してくれました。二度と間違いを犯さないと誓いましたが、それからリンターにそれを誓わせました。↩︎
  2. その中でも特に:真面目な組版者が信頼するツールは学ぶ価値があるはずだという理論で、週末をLaTeXに費やしました。もしあなたがプロの組版者なら、その価値はあります。私にとっては、CSSが午後に提供してくれたレイアウトを近似するために、難解なマクロと不可解なエラーの壁でした。私は断念し、二度と振り返ることはありませんでした。それが、本全体がウェブのボックスモデルで描かれることになった理由です。↩︎
  3. 私はひどいスペルミスをするので、VS CodeでCSpellも実行しました。これはHarperとカスタム辞書を共有していました。↩︎
  4. セルフホストだったので、オンデバイスでも実行されました。まあ、Codespace内でです。↩︎
  5. リストをグループ化しました。タイポグラフィ: validateSmallcapsとvalidateEscapedSmallcaps(スモールキャップでレンダリングされる頭字語、誤ってエスケープされない)、validateEmDashes、validateNumberRangeDashes(enダッシュ範囲)、validateQuotePunctuation、validateListPunctuation、validateBoldKeywords。構造: validateHeadingHierarchy(スキップされたレベルなし)、validateDuplicateHeadings、validateParagraphLength(テキストの壁なし)、validateMinOpenerLength、validateSectionIntros / validateSectionIntroHasLead / validateSectionIntroFinalLead / validateSectionIntroNoTldr(セクションイントロはTL;DRを繰り返さずにコンテンツに導く)、validateTldrLength、validateChapter、validateIndexIntegrity(index.ymlはディスク上のファイルと一致)。リンクと参照: validateCrossReferences、validateNoBareUrlLinkText、validateFootnotes、validateAcronymExpansion(初回使用時に展開)。コールアウト: validateCalloutBalance(マネージャーとICのペア)、validateCalloutDivs、validateRoleCalloutLabels。声と反AI: validateGitHubTense、validateOpenSourceHyphenation、validateHypotheticalHooks、validateSentenceStarters、validateDoubledWords。ハウスキーピング: validateNoTodoMarkers、validateNoTransitionTodos、validateBuildIdentifiers、validateSSML(オーディオブックマークアップ)。↩︎
  6. jscpdはプローズ固有ではありません。コードをDRYにするための素晴らしい方法です。↩︎
  7. 残りの12個、簡潔に:整合性(本自身の慣例のドリフト)、タグライン(コールアウトに含める価値のあるバンパーステッカーライン)、校正(タイポと機械的なミス)、クロスリファレンス(壊れた「章Xを参照」ポインター)、頭字語(初回使用時に展開されていない)、専門用語(「新入社員に説明する」テスト)、代替テキスト(欠落または説明不足)、証拠(理由や方法のない主張)、構造(見出し階層)、可読性(1回の読みで解析が難しい文)、包括性(文脈で判断される非包括的な言語)、強調(過剰に使用される太字、斜体、引用符)。↩︎
  8. audit-chapter-lengths.js / audit-paragraph-lengths.jsは外れ値の章やテキストの壁をフラグ付けします。reading-time.jsは各章と本全体を238 wpm(平均的な大人のノンフィクション速度)で計測します。check-epub-size.jsはサイズ予算を強制します。consistency-check.jsは「open source」対「open-source」や「async」対「asynchronous」を本全体で解決します。そしてwriting-dashboard.jsはすべてをHTMLにレンダリングします。さらに、単語数や可読性統計のためのいくつかの推奨ローカルチェッカー(proselint、GNU diction、GNU style)もあります。↩︎
  9. 単なる比喩ではありません。Kindleの最新フォーマット(KF8/AZW3)はWebKitベースのエンジン(Safariと同じレンダリング系統)でレンダリングされ、Amazon独自の-webkit- CSS拡張機能まで使用されます。Kindleの本はまさに小さなオフラインWebページです。しかし、エンジンは長年読者の手に残っているEインクモデルの長いテールにわたってゆっくりと進化するため、それが確実にサポートするHTMLとCSSは、最新のWebよりも数年遅れています。したがって「非常に簡略化された」のです。↩︎
  10. AIはまともなものを生成できたでしょう。そしてそれがまさに問題でした。まともで一般的なものは、私が5,500のチェックでテキストから洗い流そうとした失敗モードでした。カバーは、読者が単語を読む前に判断する唯一のものです。そのため、機械のデフォルトの好みを置きたくなかった最後の場所でした。人間のデザイナーはブリーフィングを受けました。アルゴリズムは受けませんでした。↩︎
  11. 長さを固定することは、こだわりではありません。物理的な本全体がその数字を中心に構築されています。ページ数は本の厚さを設定するため、背表紙の幅、そしてそれを包むカバーアートはそこから計算されます。576ページからずれると、カバーが背表紙に合わなくなります。それを修正するには、人間デザイナーにラウンドトリップしてラップを再レンダリングしてもらう必要があり、1行のコード変更ではありません。上記ゲートの詳細。↩︎
  12. 残りは同じ精神で:著作権ページが存在し、画面上で下揃えされていること。H2は本文よりも大きく、H3はH2よりも小さいこと。リンクは下線付き、コードブロックは暗い背景、インラインコードは目立つ背景を持ち、ブロッククォートは左境界線を持つこと。本文はTailwind Typographyのproseクラスを使用すること。↩︎
  13. update-revision.jsはビルドSHAとバージョンをタイトルページにスタンプし、各コピーがコミットに追跡されるようにします。links-to-footnotes.jsは印刷リンクから脚注への書き換えを行います。フォーマットごとのマニフェストが並べ替えを処理します。同じソース、微妙に異なる本。↩︎
  14. 私はGitHubで長年働いてきました。そこでは絵文字は事実上構文の一部です(リアクション、:shipit:、すべてのコメントボックスにある絵文字ピッカー)。そして、それらは定期的に新しいエンコーディングエッジケースを提示しました。絵文字は、ええ、道を見つけます。↩︎
  15. ビルドは実際には6番目の成果物(DOCX)も生成します。これは、レビュー担当者がWordで変更履歴とコメント付きでフィードバックを収集するために使用しました。公開するものではなく、作業フォーマットです。↩︎
  16. パイプラインはドラフトを作成し、自己チェックを行いますが、最終的な決定権はありません。もしこれらのいずれかを実際に公開することにした場合、ネイティブスピーカーの人間が翻訳をレビューおよび校正します。機械支援、人間承認。↩︎
  17. QAスイートはドリフトを検出しますが、トランスクリプトの差分は平坦な読み方や微妙に間違った強調を聞き取れません。そのため、出荷前に、完成したナレーションを最初から最後まで聞き、すべての単語を人間が耳でチェックしました。↩︎
  18. 完全なリスト、メンテナーに感謝します:Tailwind CSSおよびTailwind Typography、Pandoc、WeasyPrint、Ghostscript、qpdf、Poppler、AdobeによるSource Serif 4、Source Sans 3、およびSource Code Pro、Twemoji、ImageMagick、sharp、SVGO、PostCSSおよびcssnano、RemarkおよびRetext(および数え切れないほどのエコシステムプラグイン)、textlint、markdownlint、Prettier、Harper、Vitest、Playwrightおよびaxe-core、Ace by DAISY、EPUBCheck、htmlproofer、lychee、html-validate、Pillow、LanguageTool、Vale、proselint、GNU Diction、yamllint、js-yaml、jscpd、およびjust。↩︎
  19. 例として、私の履歴書は印刷専用のWebページで、ビルドが直接PDFにレンダリングされます。これは本とは異なるエンジン(ここではヘッドレスChrome、あちらはWeasyPrint)ですが、同じ「電子書籍はトレンチコートを着たウェブサイトである」という考え方で、紙に向けられています。↩︎