Substantial documentation improvements

docs/guide/installation.md

@@ -0,0 +1,46 @@
+This is this installation guide for Rojo **0.5.x**.
+
+[TOC]
+
+## Overview
+Rojo has two components:
+
+* The command line interface (CLI)
+* The Roblox Studio plugin
+
+!!! info
+    It's important that your installed version of the plugin and CLI are compatible.
+
+    The plugin will show errors in the Roblox Studio output window if there is a version mismatch.
+
+## Installing the CLI
+
+### Installing from GitHub
+If you're on Windows, there are pre-built binaries available from Rojo's [GitHub Releases page](https://github.com/LPGhatguy/rojo/releases).
+
+The Rojo CLI must be run from the command line, like Terminal.app on MacOS or `cmd.exe` on Windows. It's recommended that you put the Rojo CLI executable on your `PATH` to make this easier.
+
+### Installing from Cargo
+If you have Rust installed, the easiest way to get Rojo is with Cargo!
+
+To install the latest 0.5.0 alpha, use:
+
+```sh
+cargo install rojo --version 0.5.0-alpha.11
+```
+
+## Installing the Plugin
+
+### Installing from GitHub
+The Rojo Roblox Studio plugin is available from Rojo's [GitHub Releases page](https://github.com/LPGhatguy/rojo/releases).
+
+Download the attached `rbxm` file and put it into your Roblox Studio plugins folder. You can find that folder by pressing **Plugins Folder** from your Plugins toolbar in Roblox Studio:
+
+!['Plugins Folder' button in Roblox Studio](../images/plugins-folder-in-studio.png)
+{: align="center" }
+
+### Installing from Roblox.com
+Visit [Rojo's Roblox.com Plugin page](https://www.roblox.com/library/1997686364/Rojo-0-5-0-alpha-3) in Roblox Studio and press **Install**.
+
+## Visual Studio Code Extension
+If you use Visual Studio Code, you can install [Evaera's unofficial Rojo extension](https://marketplace.visualstudio.com/items?itemName=evaera.vscode-rojo), which will install both halves of Rojo for you. It even has a nifty UI to sync files and start/stop the Rojo server!

docs/guide/migrating-to-epiphany.md

@@ -0,0 +1,58 @@
+Rojo underwent a large refactor during most of 2018 to enable a bunch of new features and lay groundwork for lots more in 2019. As such, Rojo **0.5.x** projects are not compatible with Rojo **0.4.x** projects.
+
+[TOC]
+
+## Supporting Both 0.4.x and 0.5.x
+Rojo 0.5.x uses a different name for its project format. While 0.4.x used `rojo.json`, 0.5.x uses `default.project.json`, which allows them to coexist.
+
+If you aren't sure about upgrading or want to upgrade gradually, it's possible to keep both files in the same project without causing problems.
+
+## Upgrading Your Project File
+Project files in 0.5.x are more explicit and flexible than they were in 0.4.x. Project files can now describe models and plugins in addition to places.
+
+This new project file format also guards against two of the biggest pitfalls when writing a config file:
+
+* Using a service as a partition target directly, which often wiped away extra instances
+* Defining two partitions that overlapped, which made Rojo act unpredictably
+
+The biggest change is that the `partitions` field has been replaced with a new field, `tree`, that describes the entire hierarchy of your project from the top-down.
+
+A project for 0.4.x that syncs from the `src` directory into `ReplicatedStorage.Source` would look like this:
+
+```json
+{
+    "name": "Rojo 0.4.x Example",
+    "partitions": {
+        "path": "src",
+        "target": "ReplicatedStorage.Source"
+    }
+}
+```
+
+In 0.5.x, the project format is more explicit:
+
+```json
+{
+    "name": "Rojo 0.5.x Example",
+    "tree": {
+        "$className": "DataModel",
+        "ReplicatedStorage": {
+            "$className": "ReplicatedStorage",
+            "Source": {
+                "$path": "src"
+            }
+        }
+    }
+}
+```
+
+For each object in the tree, we define *metadata* and *children*.
+
+Metadata begins with a dollar sign (`$`), like `$className`. This is so that children and metadata can coexist without creating too many nested layers.
+
+All other values are considered children, where the key is the instance's name, and the value is an object, repeating the process.
+
+## Migrating Unknown Files
+If you used Rojo to sync in files as `StringValue` objects, you'll need to make sure those files end with the `txt` extension to preserve this in Rojo 0.5.x.
+
+Unknown files are now ignored in Rojo instead of being converted to `StringValue` objects.

docs/guide/new-game.md

@@ -0,0 +1,90 @@
+[TOC]
+
+## Creating the Rojo Project
+To use Rojo to build a game, you'll need to create a new project file, which tells Rojo how to turn your files into a Roblox place.
+
+First, create a new folder to contain the files for your game and open up a new terminal inside of it, like cmd.exe or Bash.
+
+It's convenient to make the folder from the command line:
+
+```sh
+mkdir my-new-project
+cd my-new-project
+```
+
+Inside the folder, initialize a new Rojo project:
+
+```sh
+rojo init
+```
+
+Rojo will make a small project file in your directory, named `default.project.json`. It matches the "Baseplate" template from Roblox Studio, except that it'll take any files you put in a folder called `src` and put it into `ReplicatedStorage.Source`.
+
+Speaking of files, make sure to create a directory named `src` in this folder, or Rojo will be upset about missing files!
+
+```sh
+mkdir src
+```
+
+Let's also add a Lua file, `hello.lua` to the `src` folder, so that we can make this project our own.
+
+```sh
+echo 'return "Hello, Rojo!"' > src/hello.lua
+```
+
+## Building Your Place
+Now that we have a project, one thing we can do is build a Roblox place file for our project. This is a great way to get started with a project quickly with no fuss.
+
+All we have to do is call `rojo build`:
+
+```sh
+rojo build -o MyNewProject.rbxlx
+```
+
+If you open `MyNewProject.rbxlx` in Roblox Studio now, you should see a `Folder` containing a `ModuleScript` under `ReplicatedStorage`!
+
+!!! info
+    To generate a binary place file instead, use `rbxl`. Note that support for binary model/place files (`rbxm` and `rbxl`) is very limited in Rojo presently.
+
+## Live-Syncing into Studio
+Building a place file is great for starting to work on a game, but for active iteration, you'll want something faster.
+
+In Roblox Studio, make sure the Rojo plugin is installed. If you need it, check out [the installation guide](installation) to learn how to install it.
+
+To expose your project to the plugin, you'll need to start a new **live sync session** from the command line:
+
+```sh
+rojo serve
+```
+
+You should see output like this in your terminal:
+
+```sh
+$ rojo serve
+Rojo server listening on port 34872
+```
+
+Switch into Roblox Studio and press the **Connect** button on the Rojo plugin toolbar. A dialog should appear:
+
+![Rojo plugin connection dialog](../images/connection-dialog.png)
+{: class="feature-image" align="center" }
+
+If the port number doesn't match the output from the command line, change it, and then press **Connect**.
+
+If all went well, you should now be able to change files in the `src` directory and watch them sync into Roblox Studio in real time!
+
+## Uploading Your Place
+Aimed at teams that want serious levels of automation, Rojo can upload places to Roblox.com automatically.
+
+You'll need an existing game on Roblox.com as well as the `.ROBLOSECURITY` cookie of an account that has write access to that game.
+
+!!! warning
+    It's recommended that you set up a Roblox account dedicated to deploying your game instead of your personal account in case your security cookie is compromised.
+
+Generating and publishing your game is as simple as:
+
+```sh
+rojo upload --asset_id [PLACE ID] --cookie "[SECURITY COOKIE]"
+```
+
+An example project is available on GitHub that deploys to Roblox.com from GitHub and Travis-CI automatically: [https://github.com/LPGhatguy/roads](https://github.com/LPGhatguy/roads)