Placeholders
Placeholders represent values that the user must replace before using a provided sample input.
Placeholder rules are well-documented in the Google Developer Documentation Style Guide. This style guide does not attempt to reproduce their efforts, which you can consult. Instead, this page documents more common topics that occur regularly in writing Lucidworks documentation.
Placeholders in code samples and terminal input
Do not use pronouns such as my or your in the placeholder’s name.
When using generic placeholders in inline text, write the placeholder in all caps. Use underscores if the placeholder is multiple words long.
- Recommended
-
✅
PROJECT_NAME - Not recommended
-
✘
your-project-name
Include a note before or after the placeholder that states to replace the placeholder.
- Recommended
-
✅ Replace
APPLICATION_NAMEwith the name of your application. - Not recommended
-
✘
APPLICATION_NAME= your app name
If you need to show real-looking examples, use diverse placeholders that are not politically, sexually, or racially charged. Do not use full personal information of past or present Lucidworks employees, contractors, or vendors.
Shorten real-looking placeholders that are extremely long after approximately 10 characters. An example is the access token for the Springboard APIs. Include a note saying the value has been shortened.
Example placeholders
Sometimes it is necessary to show real-looking placeholder values.
When you need an example domain name, use example.org, example.net, or example.com.
When you need an example subdomain or directory, feel free to use subdomains or directories that a user may use on their own website or directory structure. Do not use generic placeholders such as foo or bar.
- Recommended
-
✅ Disallow
/config/ - Not recommended
-
✘ Disallow
/foo/ - Recommended
-
✅
ping archive.example.com - Not recommended
-
✘
ping subdomain.example.com
Standardized placeholders
In situations where it’s necessary to show a real-looking Customer ID and Application ID values in Springboard’s APIs, use the following values:
| Field | Placeholder | Value |
|---|---|---|
Customer ID |
|
|
Application ID |
|
|
sessionid |
|
|
queryid |
|
|
access_token |
|
|
id |
|
|
A real Springboard access_token is over 800 characters long. Publishing a full access_token example value is extremely unlikely.
|
- ✅ Recommended
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "eyJraWQiOiJ...",
"scope": "connectedsearch.query"
}These placeholders are available as attributes. To use the placeholders on the docs site, use {PLACEHOLDER_NAME} in the code sample wherever you want to include a placeholder.
If you are including a placeholder’s value in a source block, add subs=attributes to the source section of a code block so that it reads [source,LANGUAGE,subs=attributes].
Placeholders in UI screenshots
Using placeholders in UI screenshots may be necessary to show a multi-step process or to prevent an error from displaying when a field is required. When this is the case, use the names and values provided in the standardized applications or in the Google Developer Documentation Style Guide.
Resources
The following resources discuss specific placeholder topics: