DOC-13358 Fixing typos, voice, and trailing periods and semicolons #456
Conversation
| ** xref:{version-server}@server:cloud:couchbase-gcp-cloud-launcher.adoc[GCP Marketplace] | ||
| For the example code below to run, you'll need the username and password of the Administrator user that you create, and the IP address of at least one of the nodes of the cluster. | ||
| To run the example code below, you will need the username and password of the Administrator user that you create, and the IP address of a minimum of one node in the cluster. |
There was a problem hiding this comment.
I think the original "at least one" is clearer in this case?
There was a problem hiding this comment.
Agreed.
Also contractions are encouraged (but there are sentences that work better without them).
| https://adoptium.net/[OpenJDK 21 with HotSpot JVM] is recommended. | ||
|
|
||
| The code examples also assume: | ||
| It is also assumed that: |
There was a problem hiding this comment.
Prefer the original here (not the passive "It is assumed")
| * You have created your own bucket, or loaded the Travel Sample dataset. | ||
| Note, the Travel Sample dataset is installed automatically when deploying a Capella free tier cluster. | ||
| Note: The Travel Sample dataset is installed automatically when deploying a Capella free tier cluster. |
There was a problem hiding this comment.
NOTE: in capitals will turn that into an admonition block.
| For the purposes of this guide, you can use the *Organization Owner* role automatically assigned to your account during installation of the Capella cluster. | ||
| In production, Couchbase strongly recommends setting up users with more granular access roles as a best practice for data security. | ||
| Use the *Organization Owner* role automatically that is assigned to your account during installation of the Capella cluster. | ||
| In production, as a best practice and also for data security, it is strongly recommended to set up the users with more granular access roles. |
There was a problem hiding this comment.
The reordering is good! But "Couchbase strongly recommends" is better than the passive "it is strongly recommended"
There was a problem hiding this comment.
Agree - good reordering, but wrong voicing.
Part of the changes we've been making in recent years is a more opinionated statement of best practices, to prevent customers straying into problems.
| //// | ||
|
|
||
| The API reference is generated for each release and the latest can be found https://docs.couchbase.com/sdk-api/couchbase-scala-client/com/couchbase/client/scala/index.html[here]. | ||
| The API reference is generated for every release. The latest can be found https://docs.couchbase.com/sdk-api/couchbase-scala-client/com/couchbase/client/scala/index.html[here]. |
There was a problem hiding this comment.
New sentence, new line.
|
|
||
| * Couchbase Server is designed to work in the same WAN or availability zone as the client application. | ||
| If you're running the SDK on your laptop against a Capella cluster, see further information on: | ||
| If you are running the SDK on your laptop against a Capella cluster, see further information on: |
| ** xref:project-docs:compatibility.adoc#network-requirements[Network Requirements]. | ||
| ** If you have a consumer-grade router which has problems with DNS-SRV records review our xref:howtos:troubleshooting-cloud-connections.adoc#troubleshooting-host-not-found[Troubleshooting Guide]. | ||
| * Our https://www.couchbase.com/forums/c/java-sdk/5[community forum] is a great source of help. | ||
| ** If you have a consumer-grade router which has problems with the DNS-SRV records, review the xref:howtos:troubleshooting-cloud-connections.adoc#troubleshooting-host-not-found[Troubleshooting Guide]. |
There was a problem hiding this comment.
"with DNS-SRV records" was correct, revert.
| ** If you have a consumer-grade router which has problems with DNS-SRV records review our xref:howtos:troubleshooting-cloud-connections.adoc#troubleshooting-host-not-found[Troubleshooting Guide]. | ||
| * Our https://www.couchbase.com/forums/c/java-sdk/5[community forum] is a great source of help. | ||
| ** If you have a consumer-grade router which has problems with the DNS-SRV records, review the xref:howtos:troubleshooting-cloud-connections.adoc#troubleshooting-host-not-found[Troubleshooting Guide]. | ||
| * The https://www.couchbase.com/forums/c/java-sdk/5[community forum] is a great source of help. |
There was a problem hiding this comment.
I think "Our" was fine?
It does seem a bit more informal, but I think that's OK when talking about a community forum, as here.
There was a problem hiding this comment.
Could even delete some more of the whitespace lines above too, while you're at it 😂
| and remember the credentials for the user that you set up. | ||
| If you haven't already got a cluster set up, the easiest route is to https://cloud.couchbase.com/sign-up[sign up to Couchbase Capella and deploy a free tier cluster^]. | ||
| Once the set up is complete, come back to this page. | ||
| Make a note of the xref:cloud:get-started:connect.adoc[endpoint] to connect to, and remember the credentials for the user that you set up. |
There was a problem hiding this comment.
These are semi-independent clauses,
and quite happily live on separate line.
Our one-sentence-per line is aimed more at stopping people cramming multiple sentences into a line,
or preventing 80-char automatic breaks,
than stopping clauses living separately.
the overall goal should be readability for docs editors - both of source text and of diffs.
| We recommend running the latest Java LTS version (i.e. at the time of writing JDK 21) with the highest patch version available. | ||
| // Other supported Java versions will work, too. | ||
| At the time of writing JDK 21, it is recommended to run the latest Java LTS version with the highest patch version available. | ||
| // Other supported Java versions will also work. |
There was a problem hiding this comment.
Changing a commented out sentence is probably something I'd do too, just in case. :)
| Couchbase's large number of ports, across the URLs of many services, can be proxied by using a `couchbase2://` endpoint as the connection string. | ||
| Currently only compatible with recent versions of xref:operator:ROOT:concept-cloud-native-gateway.adoc[Couchbase Autonomous Operator]: | ||
| [source,scala] |
There was a problem hiding this comment.
Can we change to Java, and check the connection code is idiomatic? :-)
|
|
||
| CAUTION: When you replace a document, it's usually good practice to use xref:howtos:kv-operations.adoc#optimistic-locking[optimistic locking]. | ||
| Otherwise, changes might get lost if two people change the same document at the same time. | ||
| CAUTION: While replacing a document, it is a good practice to use xref:howtos:kv-operations.adoc#optimistic-locking[optimistic locking]. |
There was a problem hiding this comment.
I'm all for opinionated recommendations as guard rails -
in this case I need to think through some of the situations where even optimistic locking is not the best route,
and see what we should say and where before we recommend strongly.
Would value any thoughts and arguments for or agin.
| the collection name is unique within the scope. | ||
|
|
||
|
|
||
| More details can be found on the xref:concept-docs:data-model.adoc[Data Model page]. |
There was a problem hiding this comment.
A somewhat optimistic statement on my part - that linked page is one that's worth a bit of time improving.
| == Next Steps | ||
|
|
||
| Now you're up and running, try one of the following: | ||
| Now that your setup is up and running, try one of the following: |
There was a problem hiding this comment.
This sounds a bit clunky - maybe just change to:
"Now that you're up and running, try one of the following:"
| * xref:howtos:sqlpp-queries-with-sdk.adoc[Query] with our SQL-based {sqlpp} query language. | ||
| * Try longer-running queries with our xref:howtos:analytics-using-sdk.adoc[Analytics Service]. | ||
| * A xref:howtos:full-text-searching-with-sdk.adoc[Full Text Search]. | ||
| * Read about xref:concept-docs:data-services.adoc[which service fits your use case]. |
There was a problem hiding this comment.
These three bullets read as three clauses in a single sentence.
I am all for that being changed to something more consistent with our style guide, but to do so you'll need to also change the middle clause on FTS to a sentence with a verb.
| //// | ||
|
|
||
| The API reference is generated for each release and the latest can be found https://docs.couchbase.com/sdk-api/couchbase-scala-client/com/couchbase/client/scala/index.html[here]. | ||
| The API reference is generated for every release. The latest can be found https://docs.couchbase.com/sdk-api/couchbase-scala-client/com/couchbase/client/scala/index.html[here]. |
There was a problem hiding this comment.
I think every slightly blurs the individual existence of an API ref for each patch release - seeming to suggest that it could be one ref, regenerated each time that there is a release.
There is wording that would work with "every" if that's better than each for other reasons....
Co-authored-by: Hakim <[email protected]>
Co-authored-by: Hakim <[email protected]>
3 participants
DOC-13358
Fixing typos, trailing periods and semi-colons, and changing few sentences to Active Voice.
Preview link
Docs Preview
You can find the required credentials in the Preview docs for Internal Couchbase Reviews section in the following page:
https://confluence.issues.couchbase.com/wiki/spaces/DOCS/pages/1971224949/Docs+Team+demo+site+passwords