Developer docs style considerations

Table of Contents

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.

Formatting

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 as vehicle_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 the swaptitle 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

View code
'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; the Summary 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.

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.

Headings

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

Create and bind a quote

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.

Table of Contents