Adds the workspace documentation

Author: Maël Nison

lang/en/docs/workspaces.md

@@ -0,0 +1,96 @@
+---
+id: docs_workspaces
+guide: docs_workspaces
+layout: guide
+---
+
+{% include vars.html %}
+
+Workspace are a new way to setup your package architecture that's available by default starting from Yarn 1.0. It allows you to setup multiple packages in such a way that you only need to run `yarn install` once to install all of them in a single pass.
+
+### Why would you want to do this?
+
+- Your dependencies can be linked together, which means that a workspace can depend on another and always use the most up-to-date version of it, without having to run `yarn install` again like with the `file:` protocol, and with better safety mechanisms than with `yarn link`.
+
+- All your project dependencies will be installed together, which gives Yarn more latitude to better optimize them.
+
+- Yarn will use a single lockfile rather than a different one for each project.
+
+### How to use it?
+
+Add the following in a `package.json` file. Starting from now on, we'll call this directory the "workspace root":
+
+**package.json**
+
+```json
+{
+    "private": true,
+    "workspaces": [
+        "workspace-a",
+        "workspace-b"
+    ]
+}
+```
+
+Then create two subfolders named `workspace-a` and `workspace-b`. In each of them, create another `package.json` file with the following content:
+
+**workspace-a/package.json:**
+
+```json
+{
+    "name": "workspace-a",
+    "version": "1.0.0",
+
+    "dependencies": {
+        "cross-env": "5.0.5"
+    }
+}
+```
+
+**workspace-b/package.json:**
+
+```json
+{
+    "name": "workspace-b",
+    "version": "1.0.0",
+
+    "dependencies": {
+        "cross-env": "5.0.5",
+        "workspace-a": "1.0.0"
+    }
+}
+```
+
+Finally, run `yarn install` somewhere, ideally inside the workspace root. If everything works well, you should now have a similar file hierarchy:
+
+```
+/package.json
+/yarn.lock
+
+/node_modules
+/node_modules/cross-env
+/node_modules/workspace-a -> /workspace-a
+
+/workspace-a/package.json
+/workspace-b/package.json
+```
+
+And that's it! Requiring `workspace-a` from a file located in `workspace-b` will now use the exact code currently located inside your project rather than what is published on Github, and the `cross-env` package has been correctly deduped and put at the root of your project to be used by both `workspace-a` and `workspace-b`.
+
+### How does it compare to Lerna?
+
+Yarn's workspaces are the low-level primitives that tools like Lerna can (and [do](https://github.com/lerna/lerna/pull/899)!) use. They will never try to support the high-level feature that Lerna offers, but by implementing the core logic of the resolution and linking steps inside Yarn itself we hope to enable new usages and improve performances.
+
+### Tips & Tricks
+
+  - The `workspaces` field is an array containing the paths to each workspace. Since it might be tedious to keep track of each of them, this field also accepts glob patterns!
+
+### Limitations & Caveheats
+
+  - The package layout will be different between your workspace and what your users will get (the workspace dependencies will be hoisted higher into the filesystem hierarchy). Making assumptions about this layout was already hazardous since the hoisting process is not standardized, so theoretically nothing new here.
+
+  - In the example above, if `workspace-b` depends on a different version than the one referenced in `workspace-a`'s package.json, the dependency will be installed from Github rather than linked from your local filesystem. This is because some packages actually need to use the previous versions in order to build the new ones (Babel is one of them).
+
+  - Workspaces must be children of the workspace root in term of folder hierarchy. You cannot and must not reference a workspace that is located outside of this filesystem hierarchy.
+
+  - Nested workspaces are not supported at this time.