diff --git a/docs/creating-a-package.md b/docs/creating-a-package.md
index fed5cfb2a..a6265e7b0 100644
--- a/docs/creating-a-package.md
+++ b/docs/creating-a-package.md
@@ -51,7 +51,7 @@ in the _menus_ directory are added alphabetically.
 - `snippets` (**Optional**): an Array of Strings identifying the order of the
 snippets your package needs to load. If not specified, snippets in the
 _snippets_ directory are added alphabetically.
-- `activationEvents` (**Optional**): an Array of Strings identifying events that
+- `activationCommands` (**Optional**): an Array of Strings identifying commands that
 trigger your package's activation. You can delay the loading of your package
 until one of these events is triggered.
 - `providedServices` (**Optional**): an Object describing the services that your
@@ -98,9 +98,9 @@ module's `activate` method so you can restore your view to where the user left
 off.
 
 - `deactivate()`: This **optional** method is called when the window is shutting
-down. If your package is watching any files or holding external resources in any
-other way, release them here. If you're just subscribing to things on window,
-you don't need to worry because that's getting torn down anyway.
+down, or when your package is being updated or disabled. If your package is
+watching any files, holding external resources, providing commands or subscribing
+to events, release them here.
 
 ### Simple Package Code
 
@@ -127,12 +127,11 @@ module.exports =
   serialize: -> # ...
 ```
 
-Beyond this simple contract, your package has access to Atom's API. Be aware
-that since we are early in development, APIs are subject to change and we have
-not yet established clear boundaries between what is public and what is private.
-Also, please collaborate with us if you need an API that doesn't exist. Our goal
-is to build out Atom's API organically based on the needs of package authors
-like you.
+Beyond this simple contract, your package has access to [Atom's API][api]. Be aware
+that the Atom 1.0 API is mostly frozen. Refer to the API documentation for what
+is public. That said, please collaborate with us if you need an API that doesn't
+exist. Our goal is to build out Atom's API organically based on the needs of
+package authors like you.
 
 ## Style Sheets
 
@@ -490,6 +489,7 @@ registry.
 Run `apm help publish` to see all the available options and `apm help` to see
 all the other available commands.
 
+[api]: https://atom.io/docs/api/latest
 [file-tree]: https://github.com/atom/tree-view
 [status-bar]: https://github.com/atom/status-bar
 [cs-syntax]: https://github.com/atom/language-coffee-script
diff --git a/docs/your-first-package.md b/docs/your-first-package.md
index 578ca9f50..eb882abc7 100644
--- a/docs/your-first-package.md
+++ b/docs/your-first-package.md
@@ -72,12 +72,12 @@ command palette or by pressing `ctrl-alt-cmd-l`.
 
 Now open the command panel and search for the `ascii-art:convert` command. But
 it's not there! To fix this, open _package.json_ and find the property called
-`activationEvents`. Activation Events speed up load time by allowing Atom to
+`activationCommands`. Activation Events speed up load time by allowing Atom to
 delay a package's activation until it's needed. So remove the existing command
-and add `ascii-art:convert` to the `activationEvents` array:
+and add `ascii-art:convert` to the `activationCommands` array:
 
 ```json
-"activationEvents": ["ascii-art:convert"],
+"activationCommands": ["ascii-art:convert"],
 ```
 
 First, reload the window by running the command `window:reload`. Now when you
diff --git a/src/config.coffee b/src/config.coffee
index 7b925a32b..d9695fb55 100644
--- a/src/config.coffee
+++ b/src/config.coffee
@@ -83,7 +83,7 @@ ScopeDescriptor = require './scope-descriptor'
 #
 # ## Config Schemas
 #
-# We use [json schema](json-schema.org) which allows you to define your value's
+# We use [json schema](http://json-schema.org) which allows you to define your value's
 # default, the type it should be, etc. A simple example:
 #
 # ```coffee