This guide is based on Google's style guide.
- Formatting
- Inline Code
- Fenced code blocks
- Placeholders
- Use Ordinary Font for Software Products
- URL and Domains
- Use
example.comfor Example Domain - Filenames and File Paths
- File Type
- Use Quotation Marks for Inline Error Messages in Text
- Use Block Quotes for Separated Error Messages
- Graphical User Interface Elements
- User Entered Text
- Version
- Paragraphs
- Language and Style
- Punctuation
- Search Engine Optimization
Use code font to mark up code, such as:
- Class, method, attribute and enum names
- Data types (
Edm.String) - HTTP status codes/verbs/content-types
- env variables
- Command line utility names (
cf) - Console output (excluding error messages)
- Query parameter names and values
✅ instance of the BusinessPartner entity class
✅ The function returns a boolean or string.
✅ The data property contains the content of the response to your GET request.
Don't use code as English verbs or nouns. Don't pluralize code, instead pluralize the following noun.
❌ Return a list of WriteResponses
✅ Return a list of objects with type WriteResponse
❌ Call generate() to get a NewClass
✅ Call the generate() function to get a NewClass instance
When referring to a method name in text:
- omit the class name except where including it would prevent ambiguity
- put an empty pair of parentheses after a method name to indicate that it's a method
❌ This can be done by using the .asChildOf method
✅ This can be done by using the asChildOf() method
If a function is part of an instance of a class then it is a method, else it is a function.
❌ Methods such as execute() and executeHttpRequest() call getDestination() internally
✅ Functions such as execute() and executeHttpRequest() call getDestination() internally
Items that should NOT be put in code format are listed below:
- Email addresses
- Names of products, services, and organizations
- URLs that the reader is supposed to follow in a browser
Always use a language identifier to get syntax highlighting.
❌
```
npm install @sap-cloud-sdk/connectivity
```
✅
```bash
npm install @sap-cloud-sdk/connectivity
```
Use the plain shell script command without prefix.
❌
```bash
$ npm install @sap-cloud-sdk/connectivity
```
✅
```bash
npm install @sap-cloud-sdk/connectivity
```
Use all caps with underscore delimiters. Explain your placeholders. It should have a descriptive name as a default value.
❌ PLACEHOLDER-Name
❌ Placeholder-Name
❌ placeholderName
✅ PLACEHOLDER_NAME
Verify that this is rendered correctly. This does not apply if the placeholder is part of a longer string in code format (see next rule).
❌ where <YOUR-APPLICATION-NAME> is replaced by the name you specified.
✅ Replace YOUR_APPLICATION_NAME with the application name.
❌ as in a JWT issued from the XSUAA, e.g., https://yourSubdomain.localhost:8080/uaa/oauth/token.
✅ as in a JWT issued from the XSUAA, e.g., https://YOUR_SUBDOMAIN.localhost:8080/uaa/oauth/token.
❌
applications:
- name: <YOUR-APPLICATION-NAME>
path: .✅
applications:
- name: YOUR_APPLICATION_NAME
path: .Use ordinary font for the name of a project or product.
❌ You will need the Cloud Foundry CLI
❌ You will need the Cloud Foundry CLI
✅ You will need the Cloud Foundry CLI
❌ create a business partner against https://example.com as a destination.
✅ create a business partner against https://example.com as a destination.
❌ find the ID of a business partner via the endpoint http://localhost:8080/business-partner.
✅ find the ID of a business partner via the endpoint http://localhost:8080/business-partner.
❌ execute GET http://localhost:8080/business-partner/1003764
✅ execute GET request for URL http://localhost:8080/business-partner/1003764
For generic domain name in examples, use example.com.
✅ create a business partner against https://example.com as a destination.
❌ Replace the default tsconfig.json
✅ Replace the default tsconfig.json file
✅ Add your own package.json file.
Unless the filename ends with a noun
❌ Use a Dockerfile file
✅ Use a Dockerfile
✅ This creates a basic class inside the src/business-partners folder.
❌ The code is located in the YOUR_PROJECT\src\my-file.js file
✅ The code is located in YOUR_PROJECT/src/my-file.js file
❌ Save the configuration in the C:\cloudsdk\config.json file
✅ Save the configuration in the /cloudsdk/config.json file
Exception: If you describe a Windows-specific situation, you should use the appropriate file paths.
When discussing a file type generically, use the formal file type name in ordinary format.
❌ Download the EDMX file for the business partner service
✅ Download the EDMX file for the business partner service
Use only when you need to specifically mention a file ending. If the ending is case-insensitive, you should write it in lowercase.
✅ base64 ASCII (e.g. .pem) and binary (e.g. .der).
Enclose error messages in quotation marks when referring to them in text. Follow sentence-style capitalization.
❌ If you see the error Module not found: Error: Can't resolve 'https' in
✅ If you see the error "Module not found: "Error: Can't resolve 'https' in""
Use block quotes for error messages when displaying them outside of a sentence. Follow sentence-style capitalization.
❌ An error like this can occur: "Module not found: Error: Can't resolve 'https' in`"
✅
An error like this can occur:
Module not found: "Error: Can't resolve 'https' in"
Bold all graphical user interface element names, including:
- menu
- button
- dialog box
- list item
- window, etc.
Do not use italics or quotes.
❌ On the settings page, click Show API Key
✅ On the Settings page, click Show API Key
❌ In the drop-down, choose BasicAuthentication as the authentication type
✅ In the Authentication drop-down, select BasicAuthentication
❌ press the Get new access token button to retrieve a token
✅ Click Get New Access Token to retrieve a token
Don't include the type of UI element, such as button or checkbox, unless it adds needed clarity.
❌ You can start your application via the Launch button.
✅ To start the application, click Launch.
Use code format for text that should be entered by user.
❌ In the Name field, enter my-destination
✅ In the Name field, enter my-destination
Unless a text relates to a specific version, do not use formats x.y or x.y.z
❌ This mapping applies to the move to open source version 1.X.Y..
✅ This mapping applies to the move to open source version 1.
❌ In the new version we allow to specify the origin of the header.
✅ In version 2, you can specify the origin of the header.
In markdown, an empty line denotes the start of a new paragraph. Use paragraphs to structure your text into individual units.
A line break inside a paragraph is not visible in the rendered text. Using newlines after each sentence make it easier to restructure text and to view diffs of prose. AsciiDoc Recommended Practices gives an elaborate reasoning of the advantages of this practice.
❌ The SAP Cloud SDK for AI enables an exception logger once you create a logger instance somewhere in your project. The exception logger logs unhandled exceptions as if you would log the error manually.
✅ The SAP Cloud SDK for AI enables an exception logger once you create a logger instance somewhere in your project.
The exception logger logs unhandled exceptions as if you would log the error manually.
In general, use active voice instead of passive voice.
In certain cases, it's okay to use passive voice:
- To emphasize an object over an action
- To de-emphasize a subject or actor
- When the reader does not need to know who's responsible for the action
❌ We removed a bit more than 100 deprecated methods.
✅ More than 100 deprecated methods have been removed.
In general, use second person rather than first person — you instead of we.
❌ We do not guarantee any API compatibility for future updates
✅ The SAP Cloud SDK for AI does not guarantee any API compatibility for future updates
❌ We need to add resilience to our application to protect us.
✅ You need to add resilience to your application to protect yourself.
✅ We are happy to review and incorporate contributions.
When telling the reader to do something, use the imperative (implicit you).
❌ You will need to create a simple application that uses the approuter
✅ Create a simple application that uses the approuter
Often you can replace your with the or skip it.
❌ Deploy your application as usual by running the command:
✅ Deploy the application as usual by running the command:
Either try to change to second person or use the imperative form.
❌ Now that we have defined our destinations, we need to make sure that they are available in our process.
✅ Now that the destinations are defined, make sure that they are available in the process.
Be polite, but using please in a set of instructions is overdoing the politeness. Don't use please when explaining a procedure, even when explaining a difficult task.
❌ Please make sure the mail destination is configured correctly
✅ Make sure the mail destination is configured correctly
❌ Please note that the CUSTOMER_NAME and CUSTOMER_ACCOUNT_GROUP are properties of the entity
✅ Note that the CUSTOMER_NAME and CUSTOMER_ACCOUNT_GROUP are properties of the entity
Use 'please' only when what you're asking for:
- benefits us
- inconveniences a reader
- or suggests a potential issue with a product
✅ Please create a support issue
-
currently: For features, as this is implied
-
soon, new, future: Avoid in timeless documentation because such words can become outdated
-
so on: Instead use etc.
-
first-class: Socially-charged terms for technical concepts where appropriate
-
just: Filler word
-
per: Avoid per in contexts other than rate units.
❌ Per the specification
-
utilize: Don't use utilize when you mean 'use'.
❌ we utilize the passport library.
-
typically: Use to describe what is usual or expected under normal circumstances. Don't use as the first word in a sentence, as doing so can leave the meaning open to misinterpretation.
| Use | Don't Use |
|---|---|
| backend | back-end or back end |
| built-in | built in |
| click (✅ Click OK) | click on (❌Click on OK) |
| codebase | code base |
| data type | datatype |
| drop-down | dropdown |
| hardcode (verb), hardcoded (adjective) | hard-coded |
| login (noun or adjective), log in (verb) | ❌ login to CF |
| multi-tenant | multi tenant |
| dialog/menu | pop-up |
| read-only | read only |
| real time (noun), real-time (adjective) | ❌ in real-time |
| repository | repo |
| runtime (env), run time (during execution) | run-time |
Use serial (Oxford) comma before the final and/or in a series of three or more items
❌ define the get, set and clear methods.
✅ define the get, set, and clear methods.
Avoid exclamation point and ellipses (except in rare exciting moments)
❌ Enjoy the hands-on experience delivered by SAP Cloud SDK for AI developers!
Introduce a list with a complete sentence, not a partial one that's completed by the list items.
❌
You should include a circuit-breaker if:
- The resource is essential in your infrastructure and should be protected.
- The resource reacts poorly to heavy load.
✅
You should include a circuit-breaker in the following scenarios:
- The resource is essential in your infrastructure and should be protected.
- The resource reacts poorly to heavy load.
✅
The introduction of a cache is most effective in the following cases:
- The execution of a method consumes a lot of resources.
- The method is a pure function, meaning the function arguments contain all the information and no hidden state affects the result of the function.
- The function is invoked multiple times for the same arguments or context.
Don't add end punctuation if the item satisfies any of the below conditions:
- Consists of a single word
- Doesn't include a verb
- Is entirely in code font
- Is a link text
- Is a document title
Numbered lists follow the same rules that apply to general lists.
❌
You can obtain the JWT using Postman:
- create a new request
- go to the "Authorization tab of the request
- select "OAuth 2.0" as a type
✅
To obtain the JWT using Postman, follow these steps:
- Create a new request.
- Go to the Authorization tab of the request.
- In the Type drop-down, select OAuth 2.0.
Start the term with capital letter and text that follows colons with a lowercase letter. Use bold formatting for the term and punctuation. If term is an attribute, use code font. Use colon and not dash to set off a description.
❌
Typical parameters to configure a circuit-breaker are:
- "failure threshold"- Failure rate above which the circuit-breaker will open.
- "reset timeout"- The time after which the circuit-breaker will close.
- Fallback- Some alternative actions you want to perform when the breaker is open.
✅
Typical parameters to configure a circuit-breaker are:
- Failure threshold: failure rate above which the circuit-breaker will open.
- Reset timeout: the time after which the circuit-breaker will close.
- Fallback: some alternative actions you want to perform when the breaker is open.
Use lowercase when letter casing is meaningful to the information conveyed by the list, such as in a glossary of terms. ❌
MinTimeout: initial waiting time for the first retry.
✅
minTimeout: initial waiting time for the first retry.
The slug is the end part of a URL after the backslash: my-website.com/this-is-my-slug.
Writing a good slug positively affects our SEO.
By default, the slug is based on the filename of your MDX document.
To overwrite it, adjust the id property in the front matter.
Changing the file name could lead to unintended changes to the slug.
Do not include the words sap, cloud, sdk, js since our path is already cloud-sdk/docs/js/*.
❌ release-notes-sap-cloud-sdk-for-javascript-and-typescript'
✅ release-notes
A keyword is the search term we want a page to rank for most.
For example, the following would be a slug for the debug page:
❌ find-problems-in-the-sap-cloud-sdk
✅ debugging
Function words are words like “a”, “the”, and “and”. Avoid function words in slugs and only include them if they are needed to clarify the slug.
For example, the following would be a slug for a migration page:
❌ migrating-from-sap-btp-cloud-foundry-to-a-kubernetes-environment-with-the-sap-cloud-sdk
✅ migrate-from-cf-to-kubernetes
The URL of our page is sometimes shown in Google search results and influences whether our audience decides to click on our page. Therefore remove not only function words but also other unnecessary words.
For example, the following would be a slug for a troubleshooting guide page:
❌ how-to-improve-error-messages-in-the-cloud-sdk
✅ improve-logging
Use lowercase letters in slugs.
For example, the following would be a slug for our an FAQ page:
❌ Frequently-Asked-Questions
✅ frequently-asked-questions
Reference files by their relative path, e.g., ../my-file.mdx.
Changes to the id property in the front matter automatically carry over.
Otherwise you would have to adjust the reference in all files that reference a specific slug.
❌ see [JWT documentation](../retrieve-jwt)
✅ see [JWT documentation](../how-to-retrieve-jwt.mdx)
Use relative paths with ./ or ../.
Not using this notation can result in an old versioned doc linking to the latest doc.
❌ `the concept of a destination
✅ the concept of a [destination](./features/connectivity/destination.mdx)