diff --git a/docs/src/main/asciidoc/spring-cloud-release-tools.adoc b/docs/src/main/asciidoc/spring-cloud-release-tools.adoc
index 58eefb7d..13eed53c 100644
--- a/docs/src/main/asciidoc/spring-cloud-release-tools.adoc
+++ b/docs/src/main/asciidoc/spring-cloud-release-tools.adoc
@@ -47,6 +47,10 @@ $ cd spring-cloud-release-tools
 $ ./mvnw clean install
 ----
 
+IMPORTANT: You must set the value of the OAuth token. You can do it either via
+the command line `--releaser.git.oauth-token=...` or put it as an env variable in `.bashrc`
+or `.zshrc` e.g. `export RELEASER_GIT_OAUTH_TOKEN=...`
+
 === How to run it (interactive mode)
 
 Go to your project (e.g. Spring Cloud Sleuth)
@@ -59,7 +63,10 @@ $ # example of running the releaser agains Dalston.SR1 tag with 1.0.0.BUILD-SNAP
 $ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser
 ----
 
-The application will start running from your working directory.
+The application will start running from your working directory. Running this code
+follows the convention that you have the OAuth token environment variable set. It also assumes
+that you might have some custom configuration in `config/releaser.yml` file. This setting is optional - if
+you don't have that file, nothing will happen.
 
 TIP:  It is important that you clone the repository you are going to release using SSH in order for the
 `releaser` to be able to push tags and commit changes automatically.
@@ -205,7 +212,7 @@ $ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/
 === Project options
 
 - `releaser.fixed-versions` - A String to String mapping of manually set versions. E.g. `"spring-cloud-cli" -> "1.0.0.RELEASE"` will set
-the `spring-cloud-cli.version` to `1.0.0.RELEASE` regardless of what was set in `spring-cloud-release` project
+the `spring-cloud-cli.version` to `1.0.0.RELEASE` regardless of what was set in `spring-cloud-release` project. Example `--releaser.fixed-versions[spring-cloud-cli]=1.0.0.RELEASE`.
 - `releaser.git.clone-destination-dir` - Where should the Spring Cloud Release repo get cloned to. If null defaults to a temporary directory
 - `releaser.git.spring-cloud-release-git-url` - URL to Spring Cloud Release Git repository. Defaults to `https://github.com/spring-cloud/spring-cloud-release`
 - `releaser.git.oauth-token` - GitHub OAuth token to be used to interact with GitHub repo.
diff --git a/spring-cloud-release-tools-core/src/main/java/org/springframework/cloud/release/internal/pom/Projects.java b/spring-cloud-release-tools-core/src/main/java/org/springframework/cloud/release/internal/pom/Projects.java
index 12ebebca..f5d1a1d0 100644
--- a/spring-cloud-release-tools-core/src/main/java/org/springframework/cloud/release/internal/pom/Projects.java
+++ b/spring-cloud-release-tools-core/src/main/java/org/springframework/cloud/release/internal/pom/Projects.java
@@ -30,13 +30,18 @@ public class Projects extends HashSet<ProjectVersion> {
 		final ProjectVersion thisProject = new ProjectVersion(projectRoot);
 		return this.stream().filter(projectVersion -> projectVersion.projectName.equals(thisProject.projectName))
 				.findFirst()
-				.orElseThrow(() -> new IllegalStateException("Project with name [" + thisProject.projectName + "] is not present"));
+				.orElseThrow(() -> exception(thisProject.projectName));
+	}
+
+	private static IllegalStateException exception(String projectName) {
+		return new IllegalStateException("Project with name [" + projectName + "] is not present. "
+				+ "Either put it in the Spring Cloud Release project or set it via the [--releaser.fixed-versions[" + projectName + "]=1.0.0.RELEASE] property");
 	}
 
 	public ProjectVersion forName(String projectName) {
 		return this.stream().filter(projectVersion -> projectVersion.projectName.equals(projectName))
 				.findFirst()
-				.orElseThrow(() -> new IllegalStateException("Project with name [" + projectName + "] is not present"));
+				.orElseThrow(() -> exception(projectName));
 	}
 
 	public boolean containsSnapshots() {
diff --git a/spring-cloud-release-tools-spring/src/main/java/org/springframework/cloud/release/internal/sagan/SaganConfiguration.java b/spring-cloud-release-tools-spring/src/main/java/org/springframework/cloud/release/internal/sagan/SaganConfiguration.java
index ac86ccc0..b358b260 100644
--- a/spring-cloud-release-tools-spring/src/main/java/org/springframework/cloud/release/internal/sagan/SaganConfiguration.java
+++ b/spring-cloud-release-tools-spring/src/main/java/org/springframework/cloud/release/internal/sagan/SaganConfiguration.java
@@ -20,7 +20,8 @@ class SaganConfiguration {
 	}
 
 	private RestTemplate restTemplate(ReleaserProperties properties) {
-		Assert.hasText(properties.getGit().getOauthToken(), "In order to connect to Sagan you need to pass the Github OAuth token");
+		Assert.hasText(properties.getGit().getOauthToken(), "In order to connect to Sagan you need to pass the Github OAuth token. "
+				+ "You can do it via the [--releaser.git.oauth-token=...] command line argument or an env variable [export RELEASER_GIT_OAUTH_TOKEN=...].");
 		return new RestTemplateBuilder()
 				.basicAuthorization(properties.getGit().getOauthToken(), "")
 				.build();