diff --git a/README.md b/README.md
index 783ba3ed..2aa06191 100644
--- a/README.md
+++ b/README.md
@@ -153,7 +153,7 @@ public interface UserRepository extends CrudRepository<UserInfo, String> {
   /**
    * Advanced querying with N1QL derivation
    */
-  @View
+  @Query
   List<UserInfo> findByLastnameEqualsIgnoreCaseAndFirstnameStartsWithAndIsAdultTrue(String lastName, String fnamePrefix);
 }
 ```
@@ -168,8 +168,11 @@ You can alternatively write the statement yourself inside the `@Query` annotatio
 placeholder to make sure all necessary fields and metadata are selected by N1QL:
 
 ```java
-@Query("$SELECT_ENTITY$ WHERE firstname LIKE "%ck%"
+@Query("$SELECT_ENTITY$ WHERE firstname LIKE "%ck%")
 List<UserInfo> findPatrickAndJackAmongOthers();
+
+@Query("$SELECT_ENTITY$ WHERE firstname LIKE $1")
+List<UserInfo> findUsersWithTheirFirstnameLike(String likePattern);
 ```
 
 ## Using The Repository
diff --git a/src/main/asciidoc/migrating.adoc b/src/main/asciidoc/migrating.adoc
index 39b2f8ab..851b40f3 100644
--- a/src/main/asciidoc/migrating.adoc
+++ b/src/main/asciidoc/migrating.adoc
@@ -21,8 +21,8 @@ The view-backed query method has evolved and support for N1QL has been introduce
 
  * Simple View query (to return all elements emitted by a view) - @View annotated without `viewName`
  * Intermediate View query by query derivation (to provide some criteria for the view) @View annotated with `viewName`
- * N1QL with explicit statements inline - @N1QL annotated with value
- * N1QL query derivation - @N1QL annotated without value / no annotation (default)
+ * N1QL with explicit statements inline - `@Query` annotated with value
+ * N1QL query derivation - `@Query` annotated without value / no annotation (default)
 
 View backed queries are associated with the `@View` annotation, while N1QL backed queries are associated with the `@Query` annotation.
 
diff --git a/src/main/asciidoc/repository.adoc b/src/main/asciidoc/repository.adoc
index 7c8182d2..f7ce885d 100644
--- a/src/main/asciidoc/repository.adoc
+++ b/src/main/asciidoc/repository.adoc
@@ -109,7 +109,7 @@ As of version `4.0`, Couchbase Server ships with a new query language called `N1
 
 Prerequisite is to have a N1QL-compatible cluster and to have created a PRIMARY INDEX on the bucket where the entities will be stored.
 
-WARNING: If it is detected at configuration time that the cluster doesn't support N1QL while there are @N1QL annotated methods or non-annotated methods in your repository interface, a `UnsupportedCouchbaseFeatureException` will be thrown.
+WARNING: If it is detected at configuration time that the cluster doesn't support N1QL while there are `@Query` annotated methods or non-annotated methods in your repository interface, a `UnsupportedCouchbaseFeatureException` will be thrown.
 
 Here is an example:
 
diff --git a/src/main/java/org/springframework/data/couchbase/repository/query/StringN1qlBasedQuery.java b/src/main/java/org/springframework/data/couchbase/repository/query/StringN1qlBasedQuery.java
index 3960e4c1..a9b4b3a6 100644
--- a/src/main/java/org/springframework/data/couchbase/repository/query/StringN1qlBasedQuery.java
+++ b/src/main/java/org/springframework/data/couchbase/repository/query/StringN1qlBasedQuery.java
@@ -26,6 +26,10 @@ import org.springframework.data.repository.query.RepositoryQuery;
 
 /**
  * A {@link RepositoryQuery} for Couchbase, based on N1QL and a String statement.
+ * <p/>
+ * The statement can contain positional placeholders (eg. <code>name = $1</code>) that will map to the
+ * method's parameters, in the same order.
+ * <p/>
  * The statement can contain placeholders for the {@link #PLACEHOLDER_BUCKET bucket namespace},
  * the {@link #PLACEHOLDER_ENTITY ID and CAS fields} necessary for entity reconstruction or
  * a shortcut that covers {@link #PLACEHOLDER_SELECT_FROM SELECT AND FROM clauses}.