The Developer section of the help site is unique; its content includes extensive text, long blocks of code, complex sequences, and many inline references to technical elements. Please see the following guidance and rules for this content.
Endpoints and objects
Apply bold formatting when naming endpoints or other objects, even if it’s also a hyperlink and won’t appear bold to a user. Amid so much text, we want to user to be able to quickly pick out these elements when scanning. When we bold all endpoints and objects, the user will see either a blue hyperlink or bold, black text, both of which readily stand out.
Examples
- Use the getQuotableProducts endpoint.
- Obtain a quote’s details by using the endpoint getQuote.
Code
When including code in a sentence, always use code formatting
. Use code formatting for all inline references, not just code blocks. Always use code formatting for elements such as IDs and other code-related tags, elements, parameter names, etc.
Examples
- Use the getQuotableProducts endpoint (
/quote/quotable-products/
) to view the list of products (lines of business, or LOB) available for quoting. quote_number
is the required parameter.- Save the
id
asvehicle_id
.
Incorrect examples
- Use the getQuotableProducts endpoint (/quote/quotable-products/) to view the list of products (lines of business, or LOB) available for quoting.
- Quote number is the required parameter.
- Save the id as vehicle id.
Note: You can place lowercase code elements at the beginning of a sentence.
To apply code formatting, select the text you want to apply code formatting to, and then press control + option + x (Mac) or ctrl + alt + x (Windows) on your keyboard.
Note: Apply code formatting only to the text, not the spaces before or after the element. Be mindful of this as you apply your formatting.
Code blocks
Make long blocks of code expandable/collapsible using the expand title
function so readers can easily scan content when they arrive on a page.
- Use this consistently on each page; if one code block is collapsible, make them all collapsible.
- Set the
title
to View code. Set theswaptitle
to Hide code. - Include the following disclaimer, in block quote formatting, a single time at the beginning of any section or page (at your discretion) to explain the element to the reader:
Note: Blocks of code are hidden by default to make the page more navigable. Select View code and Hide code to view or hide these sections as needed.
Sample code block
'curl --location -g --request GET '/api/ quote/:"Q-PA-2018-106"/' |
Expand element
Note: Type this element directly in the Visual editor; this isn’t HTML, so you don’t need to use the WordPress Text editor.
Details
Use the details
tag to create expandable/collapsible text to make lengthy pages more navigable. Don’t use this for code; for code, use the convention described above.
- You can use
details
with any kind of text or content. - The
Details
element is what creates the expandable text; theSummary
tag gives it a title. - Make the title text bold. You can do this in the Visual or Text editors.
- In the live post, select/unselect the text to display/hide the content.
Sample details section
View additional details on Item Range
Dependencies
- Non-Prepared property_items
- Non-prepared revision_items
- Prepared item_transactions
Facts
- annualPremium
- itemEarnedPremium
- itemEndingLimit
- itemEndingPremium
- itemStartingLimit
- itemTransactionType
- itemWrittenPremium
Table 7 summarizes what’s included in Item Range. Table 7: Item Range.
Column Name | Description | Type |
annualPremium | The premium amount over a year for the policy. | float |
itemEarnedPremium | The amount of premium that was earned for a particular item over the date range specified. | float |
itemEndingLimit | The limit at the end of the range, even if the policy was canceled during the date range. | float |
itemEndingPremium | The premium at the end of the range, even if the policy was canceled during the date range. | str |
itemId | A foreign key to items. | str |
itemStartingLimit | The limit at the beginning of the range. | float |
itemTransactionType | The type of premium transaction that occurred on the item. | str |
itemTransactionalCustomFees | The change in a particular custom fee over the date range specified. | float |
itemWrittenPremium | The amount of premium that was written for a particular item over the date range specified. | float |
lastItemTransactionDate | The date of the last transaction that occured within the specified date range. | date |
policyId | A foreign key to properties. | str |
propertyId | A foreign key to properties. | str |
reportingDate | Date of report. | date |
revisionId | The foreign key that binds nearly everything. | str |
Apply details tag
Note: Type this element in the Text editor; this is HTML, so you must use the WordPress Text editor. The easiest way is to type the text you want to hide in the Visual editor, then place the
details
tags before and after it in the Text editor.
Because of the use of TOCs in the left margin in Developer content, which are driven by heading level, it’s acceptable to have stacked H2s (H2s that would be H3s on other pages).
Example
Normally, because all steps fall under the H2 Create and bind a quote using BriteQuote, the steps would use H3, but then they wouldn’t appear in the TOC, so in this capacity it’s okay to use H2s this way.
Element | Convention | Example |
---|---|---|
Attributes | Bold. Capitalization varies. | IfOutputPrecision |
Classes (predefined) | Bold. Capitalization varies. | ios filebuf BitArray |
Classes (user-defined) | Bold. Capitalization varies. | BlueTimerControl |
Command-line commands | Bold. All lowercase. | copy |
Command-line options (also known as switches or flags) | Bold. Capitalize the way the option must be typed. | /a /Aw |
Constants | Usually bold. Capitalization varies. | INT_MAX bDenyWrite CS_DBLCLKS |
Control classes | Often bold. All uppercase. | EDIT control class |
Data formats | Often bold. All uppercase. | CF_DIB format |
Data structures and their members (predefined) | Bold. Capitalization varies. | BITMAP bmBits CREATESTRUCT hInstance |
Data types | Bold. Capitalization follows that of the API. | DWORD float HANDLE |
Database names | Bold. The capitalization of database names varies. | Contoso database |
Directives | Bold. | #include #define |
Environment variables | Often all uppercase. | INCLUDE SESSIONNAME |
Error messages | Sentence-style capitalization. Enclose in quotation marks when referencing error messages in text. | An error occurred during report processing. If you see the error message, “Placeholder text in a content control contains items that aren’t valid,” remove floating objects, revision marks, or content controls from placeholder text, and try again. |
Event names | Bold. Treatment of event names varies. | In the OnClick event procedure …. |
Fields (members of a class or structure) | Bold. Treatment of field names varies. | IfHeight biPlanes |
File attributes | All lowercase. | The attrib command displays, sets, or removes the read-only, archive, system, and hidden attributes assigned to files or directories. |
File name extensions | All lowercase. | .mdb .doc |
File names (user-defined examples) | Title-style capitalization. It’s OK to use internal capital letters in file names for readability. | My Taxes for 2016 MyTaxesFor2016 |
Folder and directory names (user-defined examples) | Sentence-style capitalization. It’s OK to use internal capital letters in folder and directory names for readability. | Vacation and sick pay MyFiles\Accounting\Payroll\VacPay |
Functions (predefined) | Usually bold. Capitalization varies. | CompactDatabase CWnd::CreateEx FadePic |
Handles | All uppercase. | HWND |
Keywords (language and operating system) | Bold. Capitalization follows the application programming interface. | main True void |
Logical operators | Bold. All uppercase. | AND XOR |
Macros | Usually all uppercase. Bold if predefined. Might be monospace if user defined. | LOWORDMASKROP |
Markup language elements (tags) | Bold. Capitalization varies. | <img> <input type=text> <!DOCTYPE html> |
Mathematical constants and variables | Italic. | a2 + b2 = c2 |
Members | Bold. Capitalization varies. | ulNumCharsAllowed |
Methods | Bold. Capitalization varies. | OpenForm GetPrevious |
New terms | Italicize the first mention of a new term if you’re going to define it immediately in text. | Microsoft Exchange consists of both server and client components. |
Operators | Bold. | +, – sizeof |
Parameters | Italic. Capitalization varies. | Hdc grfFlagClientBinding |
Placeholders (in syntax and in user input) | Italic. | /v: version Enter password. |
Ports | All uppercase. | LPT1 |
Products, services, apps, and trademarks | Usually title-style capitalization. Check the Microsoft trademark list for capitalization of trademarked names. | Microsoft Arc Touch Mouse Microsoft Word Surface Pro Notepad Network Connections Makefile RC program |
Properties | Usually bold. Capitalization varies. | M_bClipped AbsolutePosition Message ID |
Registers | All uppercase. Treatment varies. | DS |
Registry settings | Subtrees (first-level items) all uppercase. Separated by underscores. Usually bold. Registry keys (second-level items) follow the capitalization of the UI. Registry subkeys (below the second level) follow the capitalization of the Regedit UI. | HKEY_CLASSES_ROOT HKEY_LOCAL_MACHINE SOFTWARE ApplicationIdentifier Microsoft |
Statements | Bold. Capitalization varies. | IMPORTS LIBRARY |
Structures | Usually bold. Capitalization varies. | ACCESSTIMEOUT |
Switches | Bold. Usually lowercase. | build: commands |
UI text or strings | Sentence-style capitalization. | Import from file Create a new resource See all your resources Manually trigger a flow Report a bug |
URLs | All lowercase for complete URLs. If necessary, line-break long URLs before a slash. Don’t hyphenate. See also URLs and web addresses. | www.microsoft.com msdn.microsoft.com/downloads |
User input | Usually lowercase, unless case sensitive. Bold or italic, depending on the element. If the user input string contains placeholder text, use italic for that text. | Enter hello world Enter -p password |
Values | All uppercase. | DIB_PAL_COLORS |
Variables | Treatment varies. | bEmpty m_nParams file_name |
XML schema elements | Bold. Capitalization varies. | ElementType element xml:space attribute |