First commit: this starts off on a pretty solid foot because we iterated on it a lot already.

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+## Topics
+
+Topics contain information that applies to web services in general (not specific to APIs).
+
+## API endpoints
+
+Each individual API should have its own markdown file in the /content directory. Use snake case for filenames.
+
+Each API file should have:
+
+- H2 naming the API (i.e. "Wobbles")
+  - description of the API
+  - H3 naming the object or resource that is retrieved/created/deleted by the API
+    - description of the method
+    - list of parameters
+    - example requests and responses
+
+Make sure the API is also included in the nav by adding it to `content.js`.
+
+### Description
+
+A one- or two-sentence description explaining what the API does (not how to use it).
+
+### Object
+
+Each API should have a description of the primary resources returned and manipulated
+using the API.
+
+- H3 naming the object (i.e. "The wobble object")
+- One sentence explaining what the object is.
+- Two-column table to describe the object:
+  - property name / type / required
+  - property description
+- If the object is severely nested, use a nested list instead of a table
+
+### Methods
+
+List all methods for interacting with the API.
+
+Each method:
+
+- H3 naming the method (i.e. "Retrieve a font")
+- Endpoint (h4?)
+  - do not include base URL in endpoint
+  - endpoints should use [three backtick markdown format with syntax highlighting](https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting) with `url` as the language
+- A description of what the method does. (NOT how to use it.)
+- (how do we define scopes?)
+- If necessary, a description of accepted values/filetypes and limits/restrictions
+- Two-column table to describe parameters
+  - parameter name
+  - parameter description and accepted values
+
+### Examples
+
+Each method should have H4 headers for examples:
+
+- Example request
+- Example request body (if applicable)
+- Example response
+
+There should be four examples under each header, one for each library. Use
+[three backtick markdown format with syntax highlighting](https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting):
+
+## Style conventions
+
+- Always JSON, never `JSON` or json.
+- Do **not** include access tokens in example URLs.
+- h2 and h3 will be included in side nav
+- code blocks/h4/blockquotes will be pushed to the right
+
+## Lingo
+
+- the parts of a JSON object are called **properties**
+- querystring parameters are called **parameters**
+
+## Formatting JSON
+
+We need to show JSON examples, but we want to make the documentation readable
+on a wide range of monitors: so it needs to be somewhat narrow and compact.
+Usually stringifying JSON with indentation of 2 spaces does the trick:
+if that isn't enough, use [json-pretty-compact-cli](https://github.com/tmcw/json-pretty-compact-cli)
+or another more tasteful formatter.