Update documentation

docs/docs/basic-usage.md

@@ -65,7 +65,7 @@ It will automatically find a suitable version constraint.
 ### Version constraints
 
 In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.
-This means any version geater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
+This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
 
 Please read [versions](/versions/) for more in-depth information on versions, how versions relate to each other, and on version constraints.
 
@@ -77,7 +77,7 @@ Please read [versions](/versions/) for more in-depth information on versions, ho
     When you specify a dependency in `pyproject.toml`, Poetry first take the name of the package
     that you have requested and searches for it in any repository you have registered using the `repositories` key.
     If you have not registered any extra repositories, or it does not find a package with that name in the
-    repositories you have specified, it falls bask on PyPI.
+    repositories you have specified, it falls back on PyPI.
     
     When Poetry finds the right package, it then attempts to find the best match
     for the version constraint you have specified.
@@ -143,7 +143,7 @@ and update the lock file with the new versions.
 
 !!!note
 
-    Poetry will display a Warning when executing an install command if `pyproject.lock` and `pyproject.toml`
+    Poetry will display a **Warning** when executing an install command if `pyproject.lock` and `pyproject.toml`
     are not synchronized.
 
 
@@ -159,5 +159,5 @@ or create a brand new one for you to always work isolated from your global Pytho
     `poetry` has been installed.
     
     What this means is if you project is Python 2.7 only you should
-    install `poetry` for you global Python 2.7 executable and use
+    install `poetry` for your global Python 2.7 executable and use
     it to manage your project.

docs/docs/cli.md

@@ -226,7 +226,7 @@ Note that, at the moment, only pure python wheels are supported.
 
 ## publish
 
-This command builds (if not already built) and publishes the package to the remote repository.
+This command publishes the package, previously built with the [`build`](#build) command, to the remote repository.
 
 It will automatically register the package before uploading if this is the first time it is submitted.
 
@@ -234,6 +234,8 @@ It will automatically register the package before uploading if this is the first
 poetry publish
 ```
 
+It can also build the package if you pass it the `--build` option.
+
 ### Options
 
 * `--repository (-r)`: The repository to register the package to (default: `pypi`).

docs/docs/faq.md

-# Third Party Libraries
+# FAQ
 
-Poetry 
+## Why is the dependency resolution process slow?
+
+While the dependency resolver at the heart of Poetry is highly optimized and
+should be fast enough for most cases, sometimes, with some specific set of dependencies,
+it can take time to find a valid solution.
+
+This is due to the fact that not all libraries on PyPI have properly declared their metadata
+and, as such, they are not available via the PyPI JSON API. At this point, Poetry has no choice
+but downloading the packages and inspect them to get the necessary information. This is an expensive
+operation, both in bandwidth and time, which is why it seems this is a long process.
+
+At the moment there is not way around it.
+
+!!!note
+
+    Once Poetry has cached the releases' information, the dependency resolution process
+    will be much faster.
+
+## Why are unbound version constraints a bad idea?
+
+A version constraint without an upper bound such as `*` or `>=3.4` will allow updates to any future version of the dependency.
+This includes major versions breaking backward compatibility.
+
+Once a release of your package is published, you cannot tweak its dependencies anymore in case a dependency breaks BC
+- you have to do a new release but the previous one stays broken.
+
+The only good alternative is to define an upper bound on your constraints,
+which you can increase in a new release after testing that your package is compatible
+with the new major version of your dependency.
+
+For example instead of using `>=3.4` you should use `~3.4` which allows all versions `<4.0`.
+The `^` operator works very well with libraries following [semantic versioning](https://semver.org).

docs/docs/index.md

@@ -60,9 +60,40 @@ If you want to install prerelease versions, you can use the `--preview` option.
 poetry self:update --preview
 ```
 
-And finally, if you want to install a spcific version you can pass it as an argument
+And finally, if you want to install a specific version you can pass it as an argument
 to `self:update`.
 
 ```bash
 poetry self:update 0.8.0
 ```
+
+
+## Enable tab completion for Bash, Fish, or Zsh
+
+`poetry` supports generating completion scripts for Bash, Fish, and Zsh.
+See `poetry help completions` for full details, but the gist is as simple as using one of the following:
+
+
+```bash
+# Bash
+poetry completions bash > /etc/bash_completion.d/poetry.bash-completion
+
+# Bash (macOS/Homebrew)
+poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion
+
+# Fish
+poetry completions fish > ~/.config/fish/completions/poetry.fish
+
+# Zsh
+poetry completions zsh > ~/.zfunc/_poetry
+```
+
+!!! note
+
+    You may need to restart your shell in order for the changes to take effect.
+    
+For `zsh`, you must then add the following line in your `~/.zshrc` before `compinit`:
+
+```bash
+fpath+=~/.zfunc
+```

docs/docs/versions.md

@@ -108,6 +108,13 @@ my-package = { path = "../my-package/" }
 my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }
 ```
 
+!!!note
+
+    You can install path dependencies in editable/development mode.
+    Just pass `--develop my-package` (repeatable as much as you want) to
+    the `install` command.
+    
+
 ### Python restricted dependencies
 
 You can also specify that a dependency should be installed only for specific Python versions:

docs/mkdocs.yml

@@ -15,6 +15,7 @@ pages:
   - Repositories: repositories.md
   - Versions: versions.md
   - The pyproject.toml file: pyproject.md
+  - FAQ: faq.md
 
 markdown_extensions:
   - codehilite