Don’t start a sentence not inside a code block with a command or code. Instead, try to move the code into the middle of the sentence. For example, you can introduce the command with a more descriptive word like “Run”.
Correct: Run the rpk topic create command to create a new topic.
Incorrect: rpk topic create creates a new topic.
Similarly, do not start a sentence with a filename.
Correct: The redpanda.yaml file contains configuration parameters.
Incorrect: redpanda.yaml contains configuration parameters.
This version is correct because the sentence starts with the definite article, providing a descriptive context before introducing the xref.
Correct:
The xref:api:ROOT:admin-api.adoc#get-/v1/broker/pre_restart_probe[`pre_restart_probe`] endpoint identifies potential risks if a broker is restarted.Incorrect:
xref:api:ROOT:admin-api.adoc#get-/v1/broker/pre_restart_probe[`pre_restart_probe`] is an endpoint.This version is incorrect because it starts directly with the xref. According to our style guidelines, sentences should not begin with a command, code snippet, or filename. Instead, the xref should be integrated into a descriptive sentence.