Minor documentation improvements.

assets/default.css

@@ -78,3 +78,37 @@ table > tbody > tr:hover {
 table a:not(.btn), .table a:not(.btn) {
     text-decoration: none;
 }
+
+.highlight .hll { background-color: #ffffcc }
+.highlight .c { color: #008000 } /* Comment */
+.highlight .err { border: 1px solid #FF0000 } /* Error */
+.highlight .k { color: #0000ff } /* Keyword */
+.highlight .cm { color: #008000 } /* Comment.Multiline */
+.highlight .cp { color: #0000ff } /* Comment.Preproc */
+.highlight .c1 { color: #008000 } /* Comment.Single */
+.highlight .cs { color: #008000 } /* Comment.Special */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gh { font-weight: bold } /* Generic.Heading */
+.highlight .gp { font-weight: bold } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { font-weight: bold } /* Generic.Subheading */
+.highlight .kc { color: #0000ff } /* Keyword.Constant */
+.highlight .kd { color: #0000ff } /* Keyword.Declaration */
+.highlight .kn { color: #0000ff } /* Keyword.Namespace */
+.highlight .kp { color: #0000ff } /* Keyword.Pseudo */
+.highlight .kr { color: #0000ff } /* Keyword.Reserved */
+.highlight .kt { color: #2b91af } /* Keyword.Type */
+.highlight .s { color: #a31515 } /* Literal.String */
+.highlight .nc { color: #2b91af } /* Name.Class */
+.highlight .ow { color: #0000ff } /* Operator.Word */
+.highlight .sb { color: #a31515 } /* Literal.String.Backtick */
+.highlight .sc { color: #a31515 } /* Literal.String.Char */
+.highlight .sd { color: #a31515 } /* Literal.String.Doc */
+.highlight .s2 { color: #a31515 } /* Literal.String.Double */
+.highlight .se { color: #a31515 } /* Literal.String.Escape */
+.highlight .sh { color: #a31515 } /* Literal.String.Heredoc */
+.highlight .si { color: #a31515 } /* Literal.String.Interpol */
+.highlight .sx { color: #a31515 } /* Literal.String.Other */
+.highlight .sr { color: #a31515 } /* Literal.String.Regex */
+.highlight .s1 { color: #a31515 } /* Literal.String.Single */
+.highlight .ss { color: #a31515 } /* Literal.String.Symbol */

define/index.md

@@ -1,6 +1,6 @@
 # Define API
 
-You can describe the operations of an API in one of the supported API definition languages:
+Describe the operations of your API in one of the supported API definition languages:
 
 * [Facility Service Definition (FSD)](/define/fsd)
 * [Swagger (OpenAPI) 2.0](/define/swagger)
@@ -15,7 +15,7 @@ API definitions can be converted between formats by doing one of the following:
 
 ## fsdgenfsd
 
-`fsdgenfsd` is used to convert a service definition between the supported API definition languages. It can also be used to "normalize" an API definition by "converting" it to the same format.
+`fsdgenfsd` is a command-line tool that can convert a service definition between the supported API definition languages. It can also be used to "normalize" an API definition by "converting" it to the same format.
 
 Install `fsdgenfsd` [as documented](/generate/tools#installation) from its [NuGet package](https://www.nuget.org/packages/fsdgenfsd/).
 

generate/index.md

@@ -1,6 +1,6 @@
 # Generate Code
 
-To generate code from a [Facility Service Definition](/define), do one of the following:
+To generate client code, server code, and/or documentation for a [Facility Service Definition](/define), do one of the following:</p>
 
 * Use the [Facility Editor](/editor). Enter an FSD or Swagger API definition, choose the desired generator, and click Download.
 * Run a [command-line tool](/generate/tools) on the command line or in a build script.
@@ -15,9 +15,7 @@ Facility supports the following code generators:
 * [JavaScript/TypeScript](/generate/javascript): Generates a JavaScript or TypeScript API client.
 * [Markdown](/generate/markdown): Generates Markdown documentation for your API.
 
-### Philosophy
-
-The official Facility code generators conform to a particular philosophy of code generation:
+The official Facility code generators conform to the following guidelines:
 
 * **Encapsulate the protocol on the client.** When a developer calls a service method using a generated client, the details of the protocol – the URL, `GET` vs. `POST`, whether the request fields are sent via query string or JSON body, which HTTP status codes are used, etc. – should be hidden from the caller, not because the details are secret, but because they are unrelated to the purpose of the call.
 * **Encapsulate the protocol on the server.** In the same way, code generated for a server implementation should provide a mechanism for the developer to implement each service method in such a way that the request fields are already extracted from the HTTP path, query string, JSON request body, etc., and in which the HTTP status code and JSON response fields are automatically determined from the response.
@@ -28,8 +26,6 @@ The official Facility code generators conform to a particular philosophy of code
 * **Avoid merging changes into generated files.** Developers should be discouraged from editing generated files, which should be replaced wholesale by code generators, not edited by them.
 * **Keep it simple.** Code generators should be as simple as possible, generating as little code as possible and supporting as few options as possible.
 
-For other code generation philosophies, check out the Swagger tools below.
-
 ## Swagger Tools
 
 By using [Swagger (OpenAPI) 2.0](/define/swagger) for your API definition, or converting your [FSD](/define/fsd) to the Swagger format, you can leverage the many [Swagger tools and code generators](http://swagger.io/tools/). For example:

index.html

@@ -4,7 +4,7 @@
 <div class="jumbotron">
   <div class="container">
     <h1>Facility <small>API Framework</small></h1>
-    <p>Helps you design, implement, document, and consume APIs with tools and libraries that work with simple API definitions.</p>
+    <p>Design, implement, document, and consume APIs with tools and libraries that work with simple API definitions.</p>
     <p>
       <a href="/why" class="btn btn-primary">Why Facility?</a>
       <a href="/start" class="btn btn-primary">Get Started</a>
@@ -14,15 +14,13 @@ <h1>Facility <small>API Framework</small></h1>
   <div class="row">
     <div class="col-sm-6">
       <h2><small>1.</small> <a href="/define">Define API</a></h2>
-      <p>Describe the operations of your API in one of the supported API definition languages.</p>
       <div class="list-group large">
         <a href="/define/fsd" class="list-group-item">Facility Service Definition (FSD)</a>
         <a href="/define/swagger" class="list-group-item">Swagger (OpenAPI) 2.0</a>
       </div>
     </div>
     <div class="col-sm-6">
       <h2><small>2.</small> <a href="/generate">Generate Code</a></h2>
-      <p>Use tools to generate client code, server code, and documentation in many different languages and frameworks.</p>
       <div class="list-group large">
         <a href="/generate/csharp" class="list-group-item">C# (.NET client)</a>
         <a href="/generate/aspnet" class="list-group-item">ASP.NET</a>