Provide basic Celerity documentation.

src/docs/flavortext/soon_static_resources.diviner

@@ -1,10 +1,13 @@
 @title Things You Should Do Soon: Static Resources
 @group flavortext
 
-
 Over time, you'll write more JS and CSS and eventually need to put systems in
 place to manage it.
 
+This is part of @{article:Things You Should Do Soon}, which describes
+architectural problems in web applications which you should begin to consider
+before you encounter them.
+
 = Manage Dependencies Automatically =
 
 The naive way to add static resources to a page is to include them at the top

src/docs/technical/celerity.diviner

@@ -0,0 +1,65 @@
+@title Celerity Technical Documentation
+@group celerity
+
+Technical overview of the Celerity system.
+
+= Overview =
+
+Celerity is a static resource (CSS and JS) management system, which handles:
+
+  - Keeping track of which resources a page needs.
+  - Generating URIs for the browser to access resources.
+  - Managing dependencies between resources.
+  - Packaging resources into fewer HTTP requests for performance.
+  - Preprocessing resources (e.g., stripping comments and whitespace).
+  - Delivering resources and managing resource cache lifetimes.
+  - Interfacing with the client to manage resources.
+
+Celerity is an outgrowth of the //Haste// system at Facebook. You can find more
+information about Celerity here:
+
+  - @{article:Things You Should Do Soon: Static Resources} describes the history
+    and context of the system and the problems it solves.
+  - @{article:Adding New CSS and JS} provides a developer guide to using
+    Celerity.
+
+= Class Relationships =
+
+Celerity's primary API is @{function:require_celerity_resource}, which marks a
+resource for inclusion when a response is rendered (e.g., when the HTML page is
+generated, or when the response to an Ajax request is built). For instance, if
+you use a CSS class like "widget-view", you must ensure the appropriate CSS is
+included by calling ##require_celerity_resource('widget-view-css')## (or
+similar), at your use site.
+
+This function uses @{class:CelerityAPI} to access the active
+@{class:CelerityStaticResourceResponse} and tells it that it needs to include
+the resource later, when the response actually gets built. (This layer of
+indirection provides future-proofing against certain complex situations Facebook
+eventually encountered).
+
+When the time comes to render the response, the page renderer uses
+@{class:CelerityAPI} to access the active
+@{class:CelerityStaticResourceResponse} and requests that it render out
+appropriate references to CSS and JS resources. It uses
+@{class:CelerityResourceMap} to determine the dependencies for the requested
+resources (so you only have to explicitly include what you're actually using,
+and not all of its dependencies) and any packaging rules (so it may be able to
+generate fewer resource requests, improving performance). It then generates
+##<script />## and ##<link />## references to these resources.
+
+These references point at ##/res/## URIs, which are handled by
+@{class:CelerityResourceController}. It responds to these requests and delivers
+the relevant resources and packages, managing cache lifetimes and handling any
+neessary preprocessing. It uses @{class:CelerityResourceMap} to locate resources
+and read packaging rules.
+
+The dependency and packaging maps are generated by
+##scripts/celerity_mapper.php##, which updates
+##src/__celerity_resource_map__.php##. This file is automatically included and
+just calls @{function:celerity_register_resource_map} with a large blob of
+static data to populate @{class:CelerityResourceMap}.
+
+@{class:CelerityStaticResourceResponse} also manages some Javelin information,
+and @{function:celerity_generate_unique_node_id} uses this metadata to provide
+a better uniqueness guarantee when generating unique node IDs.