ドキュメント
ドキュメント
Foundation のドキュメントは、マニュアルが付いたパンフレットではありません。ソフトウェアを運用するための知識そのもので、説明するコードと同じリポジトリで公開されています。だから説明と実装が離れてしまうことがなく、この先どうなってもあなたの手元に残ります。
ここで公開されているものは、すべて公開です
Foundation が自分のプロジェクトに合うかどうかを決める前に、すべてを読むことができます。アカウントも、誰かとのやり取りも必要なく、自分の速さで手順を追えます。鍵のかかった部分はなく、顧客だけが読める版もありません。
これはプロジェクトの作り方の一部として意図されたものです。プラットフォームが本当に再利用できるのは、導入し、設定し、公開し、最新の状態に保つために必要な知識が、書いた人の手元ではなくソフトウェアと一緒に移動するときです。
運用マニュアル
八つのマニュアルがあり、それぞれが自分の主題についての拠り所です。いずれも、Foundation を初めて見る人に向けて書かれています。
- Adoption — 新しい Foundation プロジェクトの作成
固定された Foundation のリリースから新しいプロジェクトを起こす方法。プラットフォームと運用の知識を最初から一緒に持った状態で始められます。
- Deployment — 検証済みのサイトを公開する
サイトを公開するまでの流れと、その前に行う重要な確認。ドメインと DNS のように、アカウントの持ち主しかできない作業も含みます。
- Foundation Upgrade — 新しいリリースの取り込み
新しい Foundation のリリースを採用する方法と、プラットフォーム側のファイルと利用者側のファイルを分ける仕組みが、設定、コンテンツ、アセット、ブランドをどう守るか。
- Site customization — サイトのカスタマイズ
利用者側のための手引きです。何を変更するのか、言語をどう追加するのか、サイトの身元が実際どこにあるのか。
- Branding and assets — ブランドとアセット
サイトが自前の作品に差し替えるアセットの役割と、それぞれの差し替え方。
- Content management — コンテンツの管理
ページ、ナビゲーション、サイトの文言がファイルとしてどう保存され、どう追加・変更するのか。
- Validation — 検証のゲート
変更を受け入れる前に何が検査されるのか、そしてそれを自分で実行する方法。
- Troubleshooting — 問題の切り分け
何かが動かないときの最初の手順。公開時の出力から、表示されないページまで。
読むのにアカウントも許可も要りません
マニュアルは、誰でも読んで実行できるように書かれています。登録も購読もなく、Provelopment と話した人だけが開ける部分もありません。ただし、ドキュメントにできないことが一つあります。アカウントへのアクセスが必要な作業（DNS の設定など）を代わりに行うことです。それはアカウントの持ち主が行う必要があります。
どこから始めるか
もっとも時間を無駄にしない順序です。各段階で、それを扱う文書を示します。
Foundation とは何かを読む
リポジトリの README。プラットフォームが提供するもの、意図的に含めないもの、その上に作ったサイトがどう見えるか。
読み進める前に、動かして見る
ローカルで起動し、基本のサイトを触ってみてください。使ってみた一時間のほうが、仕様を一日読むより多くの疑問に答えます。
どう持つかを決める
一つのサイトか、複数か。自分のアカウントか、運用を任せる形か。この決定が、ほかのどの技術的な選択よりも多くを決めます。
自分のプロジェクトを起こす
Adoption マニュアル。Foundation のリリースからプロジェクトを作り、プラットフォームと運用の知識を最初から一緒に持ちます。
自分のものにする
Site customization と Branding and assets。身元、コンテンツ、言語、アセット。プラットフォームを書き換えるのではなく、設定とファイルで行います。
自分のドメインで公開する
Deployment マニュアルと公開手順書。ドメインの持ち主しかできない DNS の作業も含みます。
最新の状態に保つ
新しいリリースを採用するときは Foundation Upgrade、検証のゲートが何を証明するかは Validation で確認します。
マニュアルが前提にしていること、していないこと
マニュアルは、Foundation を初めて見る、力のある開発者に向けて書かれています。端末を使い、パッケージマネージャを実行し、ファイルを編集し、ウェブアプリケーションをどこかの事業者に公開できることを前提にします。フレームワークを書いた経験は前提にしませんし、何かをする前にアーキテクチャ文書をすべて読むことも前提にしません。
同時に、作業は自分で行うものだという前提もあります。手順はすべて、自分の複製のリポジトリ、自分のホスティングアカウント、自分のドメインで作業する人に向けて書かれています。アカウントの持ち主しか用意できないものが必要な手順（登録事業者の DNS 設定へのアクセスなど）では、その場でそう書かれています。後から気づくことにはなりません。
一方で、マニュアルがあなたの代わりに決めることはありません。プラットフォームが支える選択肢と、それぞれの帰結を説明しますが、どのホスティング事業者を使うか、いくつの言語を公開するか、サイトを自分で運用するかは指定しません。それは事業についての判断であり、ドキュメントの役割は、それを偶然の判断ではなく根拠のある判断にすることです。
もう一つ、先に述べておくべき限界があります。マニュアルが説明できるのは、プラットフォーム自身の挙動と、導入する側の責任です。サイトが接続する第三者のサービスの内部までは説明できませんし、そのつもりもありません。接続点が他社の製品を指している場合、その製品のドキュメントが拠り所になります。
リポジトリ直下の文書
手順ではなく、製品そのものを説明している五つのファイルです。