docs

.npmignore

@@ -1,6 +1,7 @@
 src/
 typings/
 test/
+docs/
 .gitignore
 gulpfile.babel.js
 jsconfig.json

README.md

@@ -2,40 +2,17 @@
 
 This tool assists in publishing Visual Studio Code extensions.
 
+## Get Started
+
+First, install using npm:
+
 ```
 npm install -g vsce
 ```
 
-**Note:** Before you can publish an extension to the gallery, you'll first need
-to [create a publisher](docs/pat.md).
-
-## Manifest files
-
-Every Visual Studio Code extension needs a manifest file: `package.json`.
-Make sure it has at least the following fields:
-
-* `name`
-* `version`
-* `publisher`
-* `engines["vscode"]`
-
-### Example:
-
-```json
-{
-	"name": "uuid",
-	"version": "0.0.1",
-	"publisher": "joaomoreno",
-	"engines": {
-		"vscode": "*"
-	}
-}
-```
-
-## Publishing
-
-Before publishing it is good practice to list the files that will be included
-in your extension's package:
+Then, `cd` to your extension's directory.
+It is good practice to list the files that will be included in your extension's
+package, before you actually publish:
 
 ```
 $ vsce ls
@@ -43,7 +20,7 @@ hello.js
 package.json
 ```
 
-If that looks good, you can now publish your extension:
+Publish away:
 
 ```
 $ vsce publish
@@ -51,41 +28,11 @@ Publishing uuid@0.0.1...
 Successfully published uuid@0.0.1!
 ```
 
-The extension should now appear in the gallery.
+**Note:** Before you can publish an extension to the gallery, you'll first need
+to [create a **publisher**](docs/publishers.md).
 
-## Configuration
+## Help Topics
 
-### `.vsceignore`
-
-You can create a `.vsceignore` file to exclude some files from being included
-in your extension's package. This file is a collection of
-[glob](https://github.com/isaacs/minimatch) patterns, one per line.
-For example:
-
-```
-**/*.ts
-**/tsconfig.json
-!file.ts
-```
-
-### Pre-publish step
-
-It's possible to add a pre-publish step to your manifest file. The command
-will be called everytime the extension is packaged.
-
-```json
-{
-	"name": "uuid",
-	"version": "0.0.1",
-	"publisher": "joaomoreno",
-	"engines": {
-		"vscode": "*"
-	},
-	"scripts": {
-		"vscode:prepublish": "tsc"
-	}
-}
-```
-
-This will always invoke the [TypeScript](http://www.typescriptlang.org/)
-compiler whenever the extension is packaged.
+* [About the Manifest](docs/manifest.md)
+* [About Publishers](docs/publishers.md)
+* [Advanced Usage](docs/advanced.md)

docs/advanced.md

@@ -0,0 +1,36 @@
+# Advanced Usage
+
+## `.vsceignore`
+
+You can create a `.vsceignore` file to exclude some files from being included
+in your extension's package. This file is a collection of
+[glob](https://github.com/isaacs/minimatch) patterns, one per line.
+For example:
+
+```
+**/*.ts
+**/tsconfig.json
+!file.ts
+```
+
+## Pre-publish step
+
+It's possible to add a pre-publish step to your manifest file. The command
+will be called everytime the extension is packaged.
+
+```json
+{
+	"name": "uuid",
+	"version": "0.0.1",
+	"publisher": "joaomoreno",
+	"engines": {
+		"vscode": "*"
+	},
+	"scripts": {
+		"vscode:prepublish": "tsc"
+	}
+}
+```
+
+This will always invoke the [TypeScript](http://www.typescriptlang.org/)
+compiler whenever the extension is packaged.

docs/manifest.md

@@ -0,0 +1,23 @@
+# About the Manifest
+
+Every Visual Studio Code extension needs a manifest file `package.json` at
+the root of the extension directory structure.
+Make sure it has at least the following fields:
+
+* `name`
+* `version`
+* `publisher`
+* `engines["vscode"]`
+
+For example:
+
+```json
+{
+	"name": "uuid",
+	"version": "0.0.1",
+	"publisher": "joaomoreno",
+	"engines": {
+		"vscode": "*"
+	}
+}
+```

docs/pat.md

@@ -1,3 +0,0 @@
-# About Publishers
-
-etc

docs/publishers.md

@@ -0,0 +1,55 @@
+# About Publishers
+
+## Introduction
+
+Visual Studio Code leverages
+[Visual Studio Online](https://www.visualstudio.com/products/what-is-visual-studio-online-vs)
+for its gallery services. This means that authentication, hosting and
+management of extensions is provided through that service.
+
+`vsce` is able to authenticate against Visual Studio Online through
+[Personal Access Tokens](https://www.visualstudio.com/en-us/news/2015-jul-7-vso.aspx).
+
+### Get a Personal Access Token
+
+First, login to or sign up for
+[Visual Studio Online](https://www.visualstudio.com/en-us/get-started/setup/sign-up-for-visual-studio-online)
+
+Then, from your account's home page (`https://[ACCOUNT].visualstudio.com`), go to your
+the **My Profile** page:
+
+![1](images/publishers1.png)
+
+Switch to the **Security** tab and **Add** a new Personal Access Token:
+
+![2](images/publishers2.png)
+
+Give the Personal Access Token a nice description, optionally extend its 
+expiration date to 1 year and make it access every account:
+
+![3](images/publishers2.png)
+
+The next screen will display your newly created Personal Access Token. **Copy**
+it, you'll need it to create a publisher.
+
+## Create a Publisher
+
+Pick a publisher name and run:
+
+```
+vsce publisher create PUBLISHER_NAME
+```
+
+`vsce` will ask for a Personal Access Token to create the publisher with. It will
+also remember it for future references to this publisher.
+
+## Login to a Publisher
+
+In case you already created a publisher before, you can simply run:
+
+```
+vsce publisher login PUBLISHER_NAME
+```
+
+Similarly to the `create` command, `vsce` will ask you for the Personal Access Token
+and remember it for future commands.