7Technical writing

7.1Uniform resource locators ( URLs )

Prefer references to top-level domain locations on the web. These should appear without a trailing slash. For example:

Download it for free at opera.com.

If a reference to the location includes an opening slash or intermediary slashes, or if the URL includes reference to the world-wide web (www) or hyper-text transfer protocol (http), include a trailing slash. For example:

News articles about U.S. current events can be found at nytimes.com/pages/national/index.html/.

This practice, although sometimes inaccurate, better helps establish where the location ends and where the running text begins. It clarifies when full stops are part of a location or if they are part of the sentence construction, especially when locations appear at the end of a sentence.

7.2User-interface elements

User-interface elements should be treated in a bold weight to distinguish the strings in running text. These elements should be capitalized according to how they appear in the software. If you are unsure, consult the product or someone from the product team that can verify how the strings appear. The Documentation department may also be able to locate the current capitalization.

As a general rule, Android and Windows applications use sentence casing for all user-interface elements. Linux and Mac operating systems (including iOS) use title casing for titles, buttons, and menu items. Titles, in this sense, do not mean section headings or other text inside of a window or box, but instead refer to the user-interface elements that label that window.

If working in plain text, or other format where bold styling is unavailable, UI references should be offset with double quotes.

7.3File types, names and paths

File types should be presented in all caps in running text. For example:

XML, HTML, CSS, JPEG

In web content, these should be marked with the abbr HTML tag that provides the long-form of the abbreviation in the title attribute. For example:

<abbr title="HyperText Markup Language">HTML</abbr>

If the text refers to a specific filename that includes the file's extension, then the extension appears in lowercase.

Filenames and paths should be stylized in a mono-spaced typeface to set them apart from running text. For example:

The list of terms can be found in the terms.xml file, currently located in the ~/Users/tmp/style/ directory.

Menu paths do not need to be stylized. But, they should include a '>' symbol to separate menu selections. For example:

To save a file, select File > Save.

7.4Keystrokes and combinations

Keystrokes and combinations, like those described for keyboard shortcuts, should appear in sentence casing and typeset in a way that allow the reader to distinguish between the desired keystroke and the running text.

Keystroke combinations should distinguish each key and include a '+', stylized the same as the surrounding running text, to tie the stokes together. This is to prevent the combination sign '+' from being interpreted as a keystroke that needs to be pressed.

Glyphs should be used when appropriate, such as the shift, tab, or command keys. For example:

Enter, ⌘+S, Ctrl+Shift ⇧+X

The W3C states that the HTML markup kbd "represents user input" and "typically represents keyboard input". Material published to the web may benefit from using the kbd tag to style keystrokes, to be W3C compliant as well as aid some screen readers.