Substantial documentation improvements

docs/creating-a-place.md

@@ -1,68 +0,0 @@
-[TOC]
-
-## Creating the Rojo Project
-
-To use Rojo to build a place, you'll need to create a new project file, which tells Rojo how your project is structured on-disk and in Roblox.
-
-Create a new folder, then run `rojo init` inside that folder to initialize an empty project.
-
-```sh
-mkdir my-new-project
-cd my-new-project
-
-rojo init
-```
-
-Rojo will make a small project file in your directory, named `default.project.json`. It'll make sure that any code in the directory `src` will get put into `ReplicatedStorage.Source`.
-
-Speaking of, let's make sure we create a directory named `src`, and maybe a Lua file inside of it:
-
-```sh
-mkdir src
-echo 'print("Hello, world!")' > 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 the initial build, but for actively working on your place, you'll want something quicker.
-
-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 _serve_ it from the command line:
-
-```sh
-rojo serve
-```
-
-This will start up a web server that tells Roblox Studio what instances are in your project and sends notifications if any of them change.
-
-Note the port number, then switch into Roblox Studio and press the Rojo **Connect** button in the plugins tab. Type in the port number, if necessary, and press **Start**.
-
-If everything 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 place on Roblox.com as well as the `.ROBLOSECURITY` cookie of an account that has write access to that place.
-
-!!! warning
-    It's recommended that you set up a Roblox account dedicated to deploying your place instead of your personal account in case your security cookie is compromised.
-
-Generating and uploading your place file is as simple as:
-
-```sh
-rojo upload --asset_id [PLACE ID] --cookie "[SECURITY COOKIE]"
-```

docs/extra.css

@@ -1,3 +1,13 @@
 .md-typeset__table {
   width: 100%;
+}
+
+.feature-image img {
+  border: 1px solid rgba(0, 0, 0, 0.2);
+  box-shadow: 1px 1px 4px rgba(0, 0, 0, 0.2);
+}
+
+.codehilite {
+  border: 1px solid rgba(0, 0, 0, 0.2);
+  box-shadow: 1px 1px 4px rgba(0, 0, 0, 0.2);
 }

docs/guide/installation.md

@@ -1,7 +1,8 @@
+This is this installation guide for Rojo **0.5.x**.
+
 [TOC]
 
 ## Overview
-
 Rojo has two components:
 
 * The command line interface (CLI)
@@ -35,7 +36,7 @@ The Rojo Roblox Studio plugin is available from Rojo's [GitHub Releases page](ht
 
 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)
+!['Plugins Folder' button in Roblox Studio](../images/plugins-folder-in-studio.png)
 {: align="center" }
 
 ### Installing from Roblox.com

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)

docs/reference/project-format.md

@@ -24,19 +24,70 @@ Instance Descriptions correspond one-to-one with the actual Roblox Instances in
 
 All other fields in an Instance Description are turned into instances whose name is the key. These values should also be Instance Descriptions!
 
-Instance Descriptions are fairly verbose and strict. In the future, it'll be possible for Rojo to infer class names for known services like `Workspace`.
+Instance Descriptions are fairly verbose and strict. In the future, it'll be possible for Rojo to [infer class names for known services like `Workspace`](https://github.com/LPGhatguy/rojo/issues/179).
 
 ## Instance Property Value
-The shape of Instance Property Values is defined by the [rbx_tree](https://github.com/LPGhatguy/rbx-tree) library, so it uses slightly different conventions than the rest of Rojo.
+There are two kinds of property values on instances, **implicit** and **explicit**.
+
+In the vast majority of cases, you should be able to use **implicit** property values. To use them, just use a value that's the same shape as the type that the property has:
+
+```json
+"MyPart": {
+    "$className": "Part",
+    "$properties": {
+        "Size": [3, 5, 3],
+        "Color": [0.5, 0, 0.5],
+        "Anchored": true,
+        "Material": "Granite"
+    }
+}
+```
+
+`Vector3` and `Color3` properties can just be arrays of numbers, as can types like `Vector2`, `CFrame`, and more!
+
+Enums can be set to a string containing the enum variant. Rojo will raise an error if the string isn't a valid variant for the enum.
+
+There are some cases where this syntax for assigning properties _doesn't_ work. In these cases, Rojo requires you to use the **explicit** property syntax.
+
+Some reasons why you might need to use an **explicit** property:
+
+* Using exotic property types like `BinaryString`
+* Using properties added to Roblox recently that Rojo doesn't know about yet
+
+The shape of explicit property values is defined by the [rbx-dom](https://github.com/LPGhatguy/rbx-dom) library, so it uses slightly different conventions than the rest of Rojo.
 
 Each value should be an object with the following required fields:
 
 * `Type`: The type of property to represent.
     * [Supported types can be found here](https://github.com/LPGhatguy/rbx-tree#property-type-coverage).
 * `Value`: The value of the property.
-    * The shape of this field depends on which property type is being used. `Vector3` and `Color3` values are both represented as a list of numbers, for example.
+    * The shape of this field depends on which property type is being used. `Vector3` and `Color3` values are both represented as a list of numbers, while `BinaryString` expects a base64-encoded string, for example.
 
-Instance Property Values are intentionally very strict. Rojo will eventually be able to infer types for you!
+Here's the same object, but with explicit properties:
+
+```json
+"MyPart": {
+    "$className": "Part",
+    "$properties": {
+        "Size": {
+            "Type": "Vector3",
+            "Value": [3, 5, 3]
+        },
+        "Color": {
+            "Type": "Color3",
+            "Value": [0.5, 0, 0.5]
+        },
+        "Anchored": {
+            "Type": "Bool",
+            "Value": true
+        },
+        "Material": {
+            "Type": "Enum",
+            "Value": 832
+        }
+    }
+}
+```
 
 ## Example Projects
 This project bundles up everything in the `src` directory. It'd be suitable for making a plugin or model:
@@ -61,10 +112,7 @@ This project describes the layout you might use if you were making the next hit
         "HttpService": {
             "$className": "HttpService",
             "$properties": {
-                "HttpEnabled": {
+                "HttpEnabled": true
-                    "Type": "Bool",
-                    "Value": true
-                }
             }
         },
 
@@ -85,10 +133,7 @@ This project describes the layout you might use if you were making the next hit
         "Workspace": {
             "$className": "Workspace",
             "$properties": {
-                "Gravity": {
+                "Gravity": 67.3
-                    "Type": "Float32",
-                    "Value": 67.3
-                }
             },
 
             "Terrain": {

docs/reference/sync-details.md

@@ -36,12 +36,12 @@ If a directory contains a file named `init.server.lua`, `init.client.lua`, or `i
 
 For example, these files:
 
-![Tree of files on disk](images/sync-example-files.svg)
+![Tree of files on disk](../images/sync-example-files.svg)
 {: align="center" }
 
 Will turn into these instances in Roblox:
 
-![Tree of instances in Roblox](images/sync-example-instances.svg)
+![Tree of instances in Roblox](../images/sync-example-instances.svg)
 {: align="center" }
 
 ## Localization Tables
@@ -80,7 +80,7 @@ A JSON model describing a folder containing a `Part` and a `RemoteEvent` could b
 
 It would turn into instances in this shape:
 
-![Tree of instances in Roblox](images/sync-example-json-model.svg)
+![Tree of instances in Roblox](../images/sync-example-json-model.svg)
 {: align="center" }
 
 ## Binary and XML Models

docs/rojo-alternatives.md

@@ -0,0 +1,23 @@
+There are a number of existing plugins for Roblox that move code from the filesystem into Roblox.
+
+Besides Rojo, you might consider:
+
+* [rbxmk by Anaminus](https://github.com/anaminus/rbxmk)
+* [Rofresh by Osyris](https://github.com/osyrisrblx/rofresh)
+* [RbxRefresh by Osyris](https://github.com/osyrisrblx/RbxRefresh)
+* [Studio Bridge by Vocksel](https://github.com/vocksel/studio-bridge)
+* [Elixir by Vocksel](https://github.com/vocksel/elixir)
+* [RbxSync by evaera](https://github.com/evaera/RbxSync)
+* [CodeSync by MemoryPenguin](https://github.com/MemoryPenguin/CodeSync)
+* [rbx-exteditor by MemoryPenguin](https://github.com/MemoryPenguin/rbx-exteditor)
+
+So why did I build Rojo?
+
+Each of these tools solves what is essentially the same problem from a few different angles. The goal of Rojo is to take all of the lessons and ideas learned from these projects and build a tool that can solve this problem for good.
+
+Additionally:
+
+* I think that this tool needs to be built in a compiled language without a runtime, for easy distribution and good performance.
+* I think that the conventions promoted by other sync plugins (`.module.lua` for modules, as well a single sync point) are sub-optimal.
+* I think that I have a good enough understanding of the problem to build something robust.
+* I think that Rojo should be able to do more than just sync code.

docs/why-rojo.md

@@ -1,23 +1,32 @@
-There are a number of existing plugins for Roblox that move code from the filesystem into Roblox.
+Adding a tool like Rojo to your Roblox workflow can be daunting, but it comes with some key advantages.
 
-Besides Rojo, you might consider:
+[TOC]
 
-* [rbxmk by Anaminus](https://github.com/anaminus/rbxmk)
+## External Text Editors
-* [Rofresh by Osyris](https://github.com/osyrisrblx/rofresh)
+Rojo opens the door to use the absolute best text editors in the world and their rich plugin ecosystem.
-* [RbxRefresh by Osyris](https://github.com/osyrisrblx/RbxRefresh)
-* [Studio Bridge by Vocksel](https://github.com/vocksel/studio-bridge)
-* [Elixir by Vocksel](https://github.com/vocksel/elixir)
-* [RbxSync by evaera](https://github.com/evaera/RbxSync)
-* [CodeSync by MemoryPenguin](https://github.com/MemoryPenguin/CodeSync)
-* [rbx-exteditor by MemoryPenguin](https://github.com/MemoryPenguin/rbx-exteditor)
 
-So why did I build Rojo?
+Some very popular, free editors include [Visual Studio Code](https://code.visualstudio.com) and [Sublime Text](https://www.sublimetext.com).
 
-Each of these tools solves what is essentially the same problem from a few different angles. The goal of Rojo is to take all of the lessons and ideas learned from these projects and build a tool that can solve this problem for good.
+These advanced text editors have features like multi-cursor editing, goto symbol, multi-file regex find and replace, bookmarks and much more.
 
-Additionally:
+Many Rojo VS Code users also use extensions like:
 
-* I think that this tool needs to be built in a compiled language without a runtime, for easy distribution and good performance.
+* [vscode-rbxlua](https://marketplace.visualstudio.com/items?itemName=AmaranthineCodices.vscode-rbxlua)
-* I think that the conventions promoted by other sync plugins (`.module.lua` for modules, as well a single sync point) are sub-optimal.
+* [Roblox Lua Autocompletes](https://marketplace.visualstudio.com/items?itemName=Kampfkarren.roblox-lua-autofills)
-* I think that I have a good enough understanding of the problem to build something robust.
+* [TabNine](https://tabnine.com)
-* I think that Rojo should be able to do more than just sync code.
+
+## Version Control
+By building your game (or just the scripts) as individual files on the filesystem, it becomes easy to start using professional-grade version control tools like [Git](https://git-scm.com) and [GitHub](https://github.com).
+
+Hundreds of thousands of companies and individual developers use Git to version their software projects. With Rojo, Roblox developers can take advantage of the best collaboration tool around.
+
+Using a repository hosting service like GitHub or GitLab brings powerful features to Roblox developers like code reviews and issue tracking that professional engineers can't live without.
+
+## Other Tools
+There are decades of excellent tools available that operate on files. With Rojo, it's possible to take advantage of any of them!
+
+Popular tools include:
+
+* [luacheck](https://github.com/mpeterv/luacheck), a static analysis tool to help you write better Lua
+* [ripgrep](https://github.com/BurntSushi/ripgrep), an extremely fast code search tool
+* [Tokei](https://github.com/XAMPPRocky/tokei), a tool for statistics like lines of code

mkdocs.yml

@@ -11,11 +11,15 @@ theme:
 nav:
   - Home: index.md
   - Why Rojo?: why-rojo.md
-  - Installation: installation.md
+  - Guide:
-  - Creating a Place with Rojo: creating-a-place.md
+    - Installation: guide/installation.md
-  - Migrating from 0.4.x to 0.5.x: migrating-to-epiphany.md
+    - Creating a Game with Rojo: guide/new-game.md
-  - Project Format: project-format.md
+    # - Moving an Existing Game to Rojo: guide/existing-game.md
-  - Sync Details: sync-details.md
+    - Migrating from 0.4.x to 0.5.x: guide/migrating-to-epiphany.md
+  - Reference:
+    - Project Format: reference/project-format.md
+    - Sync Details: reference/sync-details.md
+  - Rojo Alternatives: rojo-alternatives.md
   - Rojo Internals:
     - Internals Overview: internals/overview.md