Big docs reorganization and adding new guides

Gemfile

@@ -15,3 +15,4 @@ gem 'yajl-ruby',    '1.1.0'
 gem 'listen',       '1.2.2'
 gem 'guard-nanoc',  '1.0.1'
 gem 'rb-readline'
+gem 'w3c_validators'

Guardfile

@@ -2,7 +2,7 @@
 # More info at https://github.com/guard/guard#readme
 
 guard 'nanoc' do
-  watch('nanoc.yaml') # Change this to config.yaml if you use the old config file name
+  watch('config.yaml') # Change this to config.yaml if you use the old config file name
   watch('Rules')
   watch(%r{^(content|layouts|lib|static)/.*$})
 end

config.yaml

@@ -67,25 +67,16 @@ data_sources:
     type: static
     items_root: /static
 
-# Configuration for the “watch” command, which watches a site for changes and
-# recompiles if necessary.
-watcher:
-  # A list of directories to watch for changes. When editing this, make sure
-  # that the “output/” and “tmp/” directories are _not_ included in this list,
-  # because recompiling the site will cause these directories to change, which
-  # will cause the site to be recompiled, which will cause these directories
-  # to change, which will cause the site to be recompiled again, and so on.
-  dirs_to_watch: [ 'content', 'layouts', 'lib' ]
-
-  # A list of single files to watch for changes. As mentioned above, don’t put
-  # any files from the “output/” or “tmp/” directories in here.
-  files_to_watch: [ 'config.yaml', 'Rules' ]
-
-  # When to send notifications (using Growl or notify-send).
-  notify_on_compilation_success: true
-  notify_on_compilation_failure: true
-
 redirects:
+  -
+    from: /docs/basics/messaging/
+    to: /docs/guides/messaging/
   -
     from: /docs/resources/stream/(.*)
-    to: /docs/resources/app-stream/$1
+    to: /reference/resources/app-stream/$1
+  -
+    from: /docs/(resources|authentication|meta|other)/(.*)
+    to: /reference/$1/$2
+  -
+    from: /docs/basics/(.*)
+    to: /reference/make-request/$1

content/docs/guides/create-a-post.md

@@ -0,0 +1,48 @@
+---
+title: "Create a Post"
+---
+
+# Creating a Post via the API
+
+<%= access_token_required_note %>
+
+A [Post](/reference/resources/post) is the microblogging primitive of the App.net API. When a user creates a post, it appears in all of their follower's streams. Posts can have images, links, and annotations but at their simplest, they just contain a piece of text.
+
+* TOC
+{:toc}
+
+## Create a post
+
+The easiest way to create a post is to use [one of the API libraries](/docs/libraries).
+
+Using [adnpy](/docs/libraries#python)
+~~~ python
+import adnpy
+
+# Set the default access token for API calls.
+adnpy.api.add_authorization_token('your access token here')
+
+# Create a post
+post = adnpy.api.create_post(data={'text':'Hello App.net from Python!'})
+~~~
+
+Or with the [adn](/docs/libraries#ruby) Ruby gem:
+
+~~~ ruby
+require 'adn'
+
+ADN.token = 'your access token here'
+post = ADN::Post.send_post(:text => "Hello App.net from Ruby!")
+~~~
+
+If you want to send the equivalent broadcast from the API without using a library, use this curl command:
+
+~~~ sh
+curl -X POST -H "Authorization: Bearer <YOUR ACCESS TOKEN>" \
+    -H "X-adn-pretty-json: 1" -H "Content-Type: application/json" \
+    --data-ascii '{
+      "text": "Hello App.net from curl!",
+    }' \
+    \
+    'https://alpha-api.app.net/stream/0/posts'
+~~~

content/docs/guides/create-an-app.md

@@ -29,7 +29,7 @@ You will be able to change all of this later, but start by giving your app a nam
 
 Enter a website that is most closely related to this app. If it doesn't make sense for you to enter a website feel free to enter in your Alpha profile URL. (https://app.net/<YOUR USERNAME>). This will let others know who is responsible for this app.
 
-The **Callback URL** is prefilled with http://localhost:8000 as a convenience for local development. The Callback URL will be used when you [authenticate your app](/docs/authentication/) later.
+The **Callback URL** is prefilled with http://localhost:8000 as a convenience for local development. The Callback URL will be used when you [authenticate your app](/reference/authentication/) later.
 
 When you are satisfied with the information you have entered click create.
 
@@ -47,7 +47,7 @@ You can also generate your self an access token.
 
 There are a few ways to get an access token, but the easiest way to get an access token for personal use or experimentation is to generate one from your app detail page.
 
-To see a list of your current apps visit [account.app.net/developer/apps/](https://account.app.net/developer/apps/)
+To see a list of your current apps visit [account.app.net/developer/apps/](https://account.app.net/developer/apps/).
 
 ![Your Apps Dashboard](https://files.app.net/01qlWgpd.png)
 
@@ -59,9 +59,9 @@ From this screen, if you look at the second block you will see a link: 'Generate
 
 ![Scope Selection Screen](https://files.app.net/01qv_Geq.png)
 
-This is the scope authorization screen. If you have already generated a token this page may have some permissions checked already otherwise there won't be any.
+This is the scope authorization screen. If you have previously generated a token, some of these boxes may already be checked.
 
-To find out more about scopes your can [read the scope docs.](/docs/authentication/#scopes)
+To find out more about scopes your can [read the scope docs](/reference/authentication/#scopes).
 
 Once you have determined which scopes you will need select them in the form and then click generate.
 
@@ -73,17 +73,26 @@ Now you should see an access token in a textbox, then you can copy and use in a
     <b>Remember</b>: An access token is just like a password. It will allow applications to interact with the API on your behalf. So, keep it secret.
 </div>
 
-## What's Next?
+## Launching your app
 
-Now that you have an access token you can use it to access authenticated parts of the API.
+Before you learn more about the API and start building your app, we want to make sure you know about some other opportunities for when you're ready to launch your app.
 
-You could:
+### Directory
+
+We want to make sure App.net users can find all the great apps that get created so we created the [App.net Directory](https://directory.app.net/). To include your app in the directory, you must [**register your app with us**](https://alpha.app.net/developer/apps/). For more information about how the directory, please see the [Directory Requirements](https://mml.desk.com/customer/portal/articles/779115-what-are-the-criteria-for-being-accepted-into-the-app-net-directory-).
 
-* [Send a broadcast](/docs/guides/send-a-broadcast/)
 
-Or, you could build something completely new. Let us know what it is if you do.
+### Developer Incentive Program
 
+To financially reward the development of great apps, [we announced the Developer Incentive Program](http://blog.app.net/2012/09/27/announcing-the-app-net-developer-incentive-program/). If you'd like to include your app you must [**register for the Developer Incentive Program**](https://alpha.app.net/developer/enrollment/).
 
+## What's Next?
 
+Now that you have an access token you can use it to access authenticated parts of the API.
 
+You could:
+
+* [Send a broadcast](/docs/guides/send-a-broadcast/)
+* [Create a post](/docs/guides/create-a-post/)
 
+Or, you could build something completely new. We always love to see new apps.

content/docs/guides/getting-started.md

@@ -0,0 +1,55 @@
+---
+title: "Getting Started"
+---
+
+# Getting Started
+
+The App.net API provides lots of functionality that could be useful to implement into your app. This document provides an overview of those features so you can decide what features make sense in your app. Not all apps need to (or should) use all pieces of the App.net API.
+
+* TOC
+{:toc}
+
+## API Ovierview
+
+App.net provides 5 major kinds of functionality.
+
+* Identity and Authentication
+    * Sign in with App.net. This can make user management much easier.
+* Social graph
+    * Find friends from App.net. This helps solve the "cold start" problem when a user signs into your app.
+* Microblogging
+    * Publish short public updates to App.net followers.
+* Messaging
+    * Publish short public or private updates to any App.net user(s).
+* File storage
+    * Store files (photos, documents, videos) with App.net.
+
+## Get started
+
+1. [Create an app](/docs/guides/create-an-app)
+2. Generate a token for yourself and your new app
+3. Make API requests using one of our [API Libraries](/docs/libraries).
+
+## Notable API features
+
+### Messaging
+
+Channels are like a chat room. They're a time ordered series of messages that can be public, private, or restricted to a group of App.net users. The messages inside of channels can take advantage of App.net files, places, and anything else the API provides. [Chat rooms](https://directory.app.net/app/145/patter/), [Broadcasts](http://blog.app.net/2013/11/21/announcing-app-net-broadcast/), and private messages are all built on top of [App.net Messaging](/docs/guides/messaging/).
+
+### Places
+
+App.net has a locations database that can be integrated with your app. This allows you to add location to Posts or Message to enable location aware apps. See the [Places reference](/docs/references/resources/places/) for more information.
+
+### Annotations
+
+Annotations are machine readable metadata that can be attached to most App.net objects (posts, messages, users, and more). They power [checkins](https://alpha.app.net/browse/checkins/), [photos](https://alpha.app.net/browse/photos/) and other rich posts on App.net. See the [Annotations introduction](/docs/references/resources/meta/annotations/) to get started.
+
+### Files
+
+App.net gives each user space to store and share files. These files can be shared publicly, attached to posts, or sent as a private message to a friend. All App.net apps share the same file storage space so if a new photo or video app comes along, you can check it out and not have to worry about migrating all your old data. See the [Files reference](/docs/references/resources/files/) for more information.
+
+## Where to get help
+
+If you find a problem with the documentation, please [open an issue](https://github.com/appdotnet/api-spec/issues) and let us know. If you have questions about the API, the quickest way to get answers is usually the [Developer Chat Room](http://patter-app.net/room.html?channel=1383) powered by the App.net API through Patter. 
+
+During typical San Francisco business hours there are also App.net staff members available to answer questions in our [HipChat chat room](http://www.hipchat.com/garqCaGOZ). For other inquiries about account/service related issues, please email [support@app.net](mailto:support@app.net).

content/docs/basics/messaging.md → content/docs/guides/messaging.md

@@ -7,9 +7,9 @@ title: "Messaging Overview"
 * TOC
 {:toc}
 
-The App.net Messaging API allows a User to create public, private, semi-private  messages between an arbitrary number of users. If you'd like to create public messages that your App.net followers see in their streams, you should [create a post](/docs/resources/post/lifecycle/#create-a-post) with the Stream API. If you need a more flexible messaging solution, the Messaging API is for you.
+The App.net Messaging API allows a User to create public, private, semi-private  messages between an arbitrary number of users. If you'd like to create public messages that your App.net followers see in their streams, you should [create a post](/reference/resources/post/lifecycle/#create-a-post) with the Stream API. If you need a more flexible messaging solution, the Messaging API is for you.
 
-Our messaging API is built around 2 central objects: [Channels](/docs/resources/channel/) and [Messages](/docs/resources/message/). If you're familiar with the App.net Stream API, here are some analogies:
+Our messaging API is built around 2 central objects: [Channels](/reference/resources/channel/) and [Messages](/reference/resources/message/). If you're familiar with the App.net Stream API, here are some analogies:
 
 * Messages are like Posts
 * Channels are like streams of Posts
@@ -25,7 +25,7 @@ If a user is authorized to read a Channel, they can also subscribe to a channel.
 
 ## Authorization
 
-Access to Messages in a given Channel is determined by the [ACL fields](/docs/resources/channel/#acl-fields) on the Channel itself.
+Access to Messages in a given Channel is determined by the [ACL fields](/reference/resources/channel/#acl-fields) on the Channel itself.
 
 Channels can be public or private. For the purpose of access tokens, a Channel is considered public if it is readable by unauthenticated users (the `public` flag) or any authenticated ADN user (the `any_user` flag).
 
@@ -40,11 +40,11 @@ In addition, an App access token has read access to a Channel and its contents w
 
 Users indicate their interest in a given channel by subscribing to it. When a channel is created, no one is subscribed to it.
 
-[Private message channels](/docs/resources/channel/#private-message) (type `net.app.core.pm`) auto-subscribe all participants to the channel in accordance with each user's [subscription preferences](https://account.app.net/settings/privacy/#messaging).
+[Private message channels](/reference/resources/channel/#private-message) (type `net.app.core.pm`) auto-subscribe all participants to the channel in accordance with each user's [subscription preferences](https://account.app.net/settings/privacy/#messaging).
 
 To get this same behavior for non-pm channels, you include the key `auto_subscribe: true` when you create or update the Channel. This will auto-subscribe all the users on the ACLs (according to their preferences).
 
-If a user has [muted a channel](/docs/resources/channel/muting/#mute-a-channel) they will never be auto-subscribed to it.
+If a user has [muted a channel](/reference/resources/channel/muting/#mute-a-channel) they will never be auto-subscribed to it.
 
 ## Annotations
 
@@ -62,5 +62,5 @@ Messages, channel updates and marker updates are pushed as objects over the stre
 
 Much like annotation types, channel types are freeform strings; we suggest you use a reversed-domain format for any custom channel types. Core channel types are prefixed with `net.app.core` and may have additional validation imposed by the App.net API. Currently defined core channel types are:
 
-* [Private Message](/docs/resources/channel/#private-message): net.app.core.pm
-* [Broadcast Channel](/docs/resources/channel/#broadcast-channel): net.app.core.broadcast
+* [Private Message](/reference/resources/channel/#private-message): net.app.core.pm
+* [Broadcast Channel](/reference/resources/channel/#broadcast-channel): net.app.core.broadcast

content/docs/guides/send-a-broadcast.md

@@ -4,11 +4,9 @@ title: "Broadcasts and the API"
 
 # Publishing Broadcasts via the API
 
-<div class="alert alert-success alert-block">
-To start sending broadcasts directly from the API, you'll need an access token. If you're not familiar with how to get an access token, <a href='/docs/guides/create-an-app/'>check out our guide on creating an app.</a>
-</div>
+<%= access_token_required_note %>
 
-Broadcast Channels are designed to carry low-volume, high-value updates of interest to users. We call the actual updates themselves Broadcast Messages (or sometimes just "broadcasts"). Because broadcasts are built on top of the existing App.net [Channel](/docs/resources/channel/) and [Message](/docs/resources/message/) APIs, it's helpful to be familiar with them, but for simple tasks, there's not much you need to know.
+Broadcast Channels are designed to carry low-volume, high-value updates of interest to users. We call the actual updates themselves Broadcast Messages (or sometimes just "broadcasts"). Because broadcasts are built on top of the existing App.net [Channel](/reference/resources/channel/) and [Message](/reference/resources/message/) APIs, it's helpful to be familiar with them, but for simple tasks, there's not much you need to know.
 
 Just a reminder: while you can do all of this using our API, you don't have to. We have [tools for publishers](https://broadcast.app.net/manage/) to help you quickly get started pulling content in from elsewhere on the web, and you can send them manually via the web or the App.net iOS and Android apps. To get started, **we recommend that you create and set up your broadcast channel with [our web publisher tools](https://broadcast.app.net/manage/)** and only use the API to send broadcasts via the channel you created.
 
@@ -100,7 +98,7 @@ curl -X POST -H "Authorization: Bearer <YOUR ACCESS TOKEN>" \
 
 You can create broadcast channels with the API as well.
 
-Broadcast channels are created like any other channel, with a specific type value (`net.app.core.broadcast`) and a few special annotations. For information on creating channels, see the [Channel lifecycle documentation](/docs/resources/channel/lifecycle/). Broadcast channels fully support [ACLs](/docs/resources/channel/) for private applications.
+Broadcast channels are created like any other channel, with a specific type value (`net.app.core.broadcast`) and a few special annotations. For information on creating channels, see the [Channel lifecycle documentation](/reference/resources/channel/lifecycle/). Broadcast channels fully support [ACLs](/reference/resources/channel/) for private applications.
 
 Here is an example channel body, set to be public, with multiple editors, which you can POST to us: