Swift Digest
この記事の要点
- Swift の公式書籍「The Swift Programming Language」（TSPL）が、Swift 5.8 から Swift-DocC を使って公開されるようになったことが発表されました。これにより TSPL は、Documentation Workgroup の運営のもとでコンテンツのコントリビューションを受け付けられる体制になりました。
- TSPL は 2022 年 8 月にオープンソース化されており、その後 50 件を超える pull request を経て DocC への移行が完了しました。移行の過程で得た知見は DocC 自体の改善にも反映され、長文ドキュメントを書く他のプロジェクトもその恩恵を受けられます。
- 本文・翻訳・DocC のいずれにもコントリビュートできる導線が案内されており、誰でも公式書籍の改善に関われるようになりました。
何が変わるのか
TSPL が DocC を使った公開パイプラインに移行したことで、書籍に対してコミュニティからコンテンツのコントリビューションを受け付けられるようになりました。これは Documentation Workgroup の指揮のもとで進められます。
DocC への移行は書籍にとって大きな前進です。移行作業を通じて DocC 自体にも次のような機能強化が加えられました。
- 自動生成される「See Also」セクションの制御
- 新しいページ内ナビゲーション
これらの強化は TSPL に限らず、大規模・複雑なパッケージのドキュメントのように、読者を一連の流れに沿って導くタイプの DocC コンテンツでも活用できます。
背景
TSPL は 2022 年 8 月にオープンソースとして公開されました。それ以降、50 件を超える pull request をマージしながら DocC への変換が進められ、今回の発表に至っています。書籍という長文ドキュメントを DocC で扱う中で見えてきた課題が、上記のような DocC 機能の改善につながっています。
参加・利用者への影響
この記事は、Swift の公式書籍やそのドキュメント体験の改善に関心があるすべての人に向けたものです。記事では次の 3 つの関わり方が案内されています。
- TSPL に本文をコントリビュートする。 何を書けばよいかのヒントとして、プロジェクトの GitHub issues ページや、最近受理された Swift Evolution の Proposal が挙げられています。コントリビュートの手順は CONTRIBUTING.md にまとめられており、大きな変更を提案する際は Swift Documentation フォーラムカテゴリで先に相談することが推奨されています。
- 翻訳プロジェクトにコントリビュートする。 TSPL の翻訳も英語版と同じ公開パイプラインを使えるようになりました。翻訳のコントリビューターは、フォーラムの pitch スレッドや GitHub の pull request を追うことで、英語版の変更を追跡できます。
- 長文コンテンツ向けの DocC サポートを改善する。 インタラクティブなコンテンツやオフライン対応、テスト可能なコードリストのサポートなど、ドキュメント体験を向上させるための課題も残されています。アイデアは TSPL と DocC の GitHub issues ページにまとまっています。