Developer content

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.

Additional developer element
ElementConventionExample
AttributesBold. Capitalization varies.IfOutputPrecision
Classes (predefined)Bold. Capitalization varies.ios
filebuf
BitArray
Classes (user-defined)Bold. Capitalization varies.BlueTimerControl
Command-line commandsBold. All lowercase.copy
Command-line options (also known as switches or flags)Bold. Capitalize the way the option must be typed./a
/Aw
ConstantsUsually bold. Capitalization varies.INT_MAX
bDenyWrite
CS_DBLCLKS
Control classesOften bold. All uppercase.EDIT control class
Data formatsOften bold. All uppercase.CF_DIB format
Data structures and their members (predefined)Bold. Capitalization varies.BITMAP
bmBits
CREATESTRUCT
hInstance
Data typesBold. Capitalization follows that of the API.DWORD
float
HANDLE
Database namesBold. The capitalization of database names varies.Contoso database
DirectivesBold.#include
#define
Environment variablesOften all uppercase.INCLUDE
SESSIONNAME
Error messagesSentence-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 namesBold. 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 attributesAll lowercase.The attrib command displays, sets, or removes the read-only, archive, system, and hidden attributes assigned to files or directories.
File name extensionsAll 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
HandlesAll uppercase.HWND
Keywords (language and operating system)Bold. Capitalization follows the application programming interface.main
True
void
Logical operatorsBold. All uppercase.AND
XOR
MacrosUsually all uppercase. Bold if predefined. Might be monospace if user defined.LOWORD
MASKROP
Markup language elements (tags)Bold. Capitalization varies.<img>
<input type=text>
<!DOCTYPE html>
Mathematical constants and variablesItalic.a2 + b2 = c2
MembersBold. Capitalization varies.ulNumCharsAllowed
MethodsBold. Capitalization varies.OpenForm
GetPrevious
New termsItalicize 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.
OperatorsBold.+, –
sizeof
ParametersItalic. Capitalization varies.Hdc
grfFlagClientBinding
Placeholders (in syntax and in user input)Italic./v: version
Enter password.
PortsAll uppercase.LPT1
Products, services, apps, and trademarksUsually 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
PropertiesUsually bold. Capitalization varies.M_bClipped
AbsolutePosition
Message ID
RegistersAll uppercase. Treatment varies.DS
Registry settingsSubtrees (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
StatementsBold. Capitalization varies.IMPORTS
LIBRARY
StructuresUsually bold. Capitalization varies.ACCESSTIMEOUT
SwitchesBold. Usually lowercase.build: commands
UI text or stringsSentence-style capitalization.Import from file
Create a new resource
See all your resources
Manually trigger a flow
Report a bug
URLsAll 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 inputUsually 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
ValuesAll uppercase.DIB_PAL_COLORS
VariablesTreatment varies.bEmpty
m_nParams
file_name
XML schema elementsBold. Capitalization varies.ElementType element
xml:space attribute

Table of Contents