Content found in this wiki may not reflect official Church information. See Terms of Use for more information.

TechWiki:Manual of Style

From TechWiki
(Redirected from Manual of style)
Jump to navigationJump to search

The Manual of Style, often abbreviated MoS, is a style guide for TechWiki articles. The guidelines here refer to style, not wiki formatting. For wiki formatting and other wiki-specific information, see TechWiki:Guidelines.

When it comes to writing technical content, we follow these style guides:

  • Microsoft’s Manual of Style for Technical Publications, 4th edition
  • Chicago Manual of Style, 16th edition
  • Style Guide for Publications of The Church of Jesus Christ of Latter-day Saints, 3rd edition (4th edition in 2012)
  • Merriam-Webster’s Collegiate Dictionary, 11th edition.
  • Wikipedia's Manual of Style

If the Manual of Style does not specify a preferred usage or you feel a modification should be made, please discuss the issue on the talk page of this article.

General writing guidelines

This section addresses the dos.

Brevity

Keep sentences short, generally to a single idea. Avoid complex sentence constructions.

Paragraphs should also be short and centered around a single concept.

Word choice

When a word has multiple meanings, think of (or look up) the most commonly used meaning. If you aren't using the most common meaning, choose a different word. If the word has special meaning for your project, provide a definition in context or in a glossary.

Avoid words that can function as both a noun and a verb, especially when the context doesn’t clarify which function the word is serving.

Complete sentences

Complete sentences are easiest for translators to work with. Write in complete sentences, and don't break a complete sentence, such as when introducing a list.

Correct:

To obtain access to the system, you need the following:
The application provides bishops with three main functions:

Incorrect:

To obtain access to the system, you need:
The application provides bishops with:

Do not write telegraphic sentences, which omit "articles, some simple verbs, pronouns, and prepositions" (Hoft, International Technical Communication, 224) and sometimes even omit the subject. Further, include the word "that" when it is otherwise implied so that the meaning of the sentence is clear.

Example:

Upgrade complete.

In tables, items in the columns should not finish a sentence started in the column heads. Use nouns or complete sentences as column heads.

Variables and conditional text should contain complete sentences.

Tone

The Microsoft Manual of Style says, "Tone defines the relationship between the writer and the reader" (p. 105). Because of the Tech platform, our audiences will likely regard them as official Church publications, sometimes even "gospel truth," so to speak.

However, instructional products usually don't include scriptural passages or General Authority quotations. It isn't our job to pronounce Church doctrine, though we may need to include Church or department policy at times. The tone of our products should not be one of a person in authority telling others what to do.

Generally, the tone of our writing should be friendly, straightforward, clear, and not overly formal or authoritative. However, keep your audience in mind. If you are writing text that will be read by General Authorities or other priesthood leaders, be sure your text is respectful and professional. Writing for youth may allow for less formality but should still be respectful and not condescending.

Point of view

Write in second person (you and your), especially in procedures. This speaks to the person who is reading.

Conceptual material may need to be in third person if the audience is broad and the material addresses multiple roles. Always be clear about who does what.

Tense

Use present tense, including when you need to narrate the result of an action, particularly what happens on the screen.

Use future tense only when something really does happen in the future.

Examples:

A copy of the document is saved in the database.
On the effective date, your mission organization will be updated based on your transfer scenario.

Global writing

Be aware of differences among countries that may require changes in content for different locales, such as printer paper size. Accommodate these differences as needed or keep information general enough to be adaptable to any country’s situation.

When writing for an international audience, be mindful of wording that may not translate well, both literally and conceptually. Do not use idioms or other nonliteral constructions. Avoid using terms or references that are specific to a culture (including popular culture), locale, or climate.

Do not use alphabetic characters to convey information, such as labeling parts of a diagram with letters, since they aren't meaningful in all languages.

Do not make a point by calling out the definition, connotations, or etymology of terms or phrases. Such concepts are specific to a language and aren't meaningful for speakers of other languages.

Currency

Use the three-digit ISO code when specifying currency amounts when any of your audience is outside the United States. The code and a space precede the number.

Example:

The current monthly amount required for equalized countries is USD 400.

If discussing a specific amount of money applicable to multiple currencies when only a United States dollar baseline is defined, use the following construction: "USD X or the equivalent in your local currency."

Dates and times

Format dates as day, month, year. If stating dates in a data set, it is all right to shorten the month to the first three letters.

Examples:

25 December 2011
25 Dec 2011

When stating a time, include minutes even when the time is on the hour. Include periods in a.m. and p.m.

When at least part of your audience is outside Church headquarters, include time zones when discussing times. Time zones are not capitalized. Individual words should be capitalized if they are proper nouns, as in "Pacific standard time."

Example:

LDS.org will be unavailable from 11:00 a.m. to 11:00 p.m. on Saturday, July 10, mountain standard time.

If you need to refer to the same time zone multiple times, follow the guidelines for acronyms under Abbreviations and Acronyms.

If an event takes place at the same time during standard time and daylight time, then omit the word "standard" or "daylight."

Example:

The process runs nightly at 6:00 p.m. mountain time.

Other locale-specific terms

Be aware of locale-specific terms, such as ZIP code, federal, and state. Use generic terms instead.

Correct:

A postal code is required.
You may need to file national income taxes during your missionary service.

Incorrect:

A ZIP code is required.
You may need to file federal income taxes during your missionary service.

Text expansion or contraction

Be aware that when written, different languages take up different amounts of space. Many languages that use the Roman alphabet take up more space than English. Plan especially for expansion of text when space is constrained.

Humor

Avoid attempts at humor, which is largely cultural and most likely will not translate well.

Images

See the Using images section.

Contractions

Unless writing for a blog where the language may be more informal than usual, use contractions only where the word "not" is being used: isn't, don't, and so on. It is acceptable to not use the contraction when you want to emphasize the negative or to be clear.

Incorrect:

She's gone to the store.

Correct:

She isn't here.

Abbreviations and acronyms

Don't use e.g. Use for example. In user interfaces, such as accompanying a text field, it's okay to use just "Example:" to save space.

Don't use i.e. ("that is"). Avoid instances where it would be needed, since it indicates that something needs to be restated or reexplained. Aim for clarity on the first try. See also Latin phrases in Things to avoid when writing."

If a term's acronym is used multiple times in a topic, write the term out the first time, with the acronym in parentheses.

For a list of abbreviations, see the Glossary.

Example:

Church Directory of Organizations and Leaders (CDOL)

Then use the acronym afterward. If using the term only once, and some people may already know the term by the acronym, write out the term with the acronym in parentheses.

Some acronyms, like PDF, may be common enough to not write out, or the reader may not really benefit from knowing what the term stands for.

Companies, trademarks, and products

Be sure to determine the correct rendering of a company, trademark, or product.

For example, "Author-it" is the correct rendering according to the company's website, not "AuthorIT" or "Author-It." Proper rendering can be difficult to determine based on a logo, so check the company's website to see how it refers to itself and its products in its copy.

Modifiers

Place modifiers next to the grammatical element they modify. The word "only" should usually be placed after the verb rather than before it, unless "only" modifies the verb.

Correct:

It takes only one person.

Incorrect:

It only takes one person.

Alphabetizing

Avoid organizing information alphabetically, such as in tables or images, unless you are using software that can automatically reorder the information after it has been translated.

Things to avoid when writing

These guidelines are in no particular order.

Allow and can

Avoid writing about what the product allows.

It may be appropriate to use can when giving an overview or in release notes where features are discussed in general terms. But in general, avoid unnecessary explanations stating that the user can do something. Instead, go directly to instructing how to accomplish a task.

Passive voice

Don't use passive voice unless the actor is unknown or passive voice flows better and doesn't obscure meaning. Generally, identifying the actor is important to clear communication. If the text uses passive voice and hides the actor, users may not know who is responsible for that action, leaving a problematic gap in understanding.

False subjects

Avoid false subjects like "there is" and "it is." Move the real subject to the front of the sentence and use an active verb.

Easy, simply, just

Never claim that a process or procedure is easy or simple. Similarly, never introduce a procedure with the word just. You've seen documentation or marketing material that said, "Just follow these easy steps!" If you make such a claim and the user doesn't find it easy, the person may become discouraged and alienated. Don't make any kind of judgment call on how easy a task is.

Further, don't claim something is intuitive. Whether something is intuitive is subjective, so we avoid it for the same reason we avoid easy, simply, and just.

Technical jargon and alternatives

Avoid technical-sounding words like utilize (use), generate (create), execute (run), initiate (start), terminate (end), authenticate (verify), validate (check). Use technical terms only when they have specific, understood meaning for a technical audience.

Latin phrases

Don't use Latin phrases or abbreviations based on Latin phrases, such as e.g., i.e., and etc. They cause difficulty for translators, and many native English speakers don’t have a clear understanding of their meanings.

Unnecessary phrases

Leave out phrases that don't add any meaning, like "in order to" and "be able to."

Redundancies in wording

Avoid redundancies like these:

  • lift up
  • each one
  • return again
  • in the morning at 10:00 a.m.

A common redundancy in speech is "the reason is because." Watch out for it in writing; use only the reason is or because, not both.

When providing a list of examples or "included" items, do not end the list with phrases like "and so on."

Long noun clusters (modifier strings)

Avoid using more than two nouns to modify the main noun. Multiple noun modifiers create ambiguity and are problematic for translators. Use prepositional phrases to clarify meaning.

Incorrect:

mission housing expense amount

Correct:

housing expense amount for the mission
mission’s housing expense amount

Symbols

Don't substitute symbols for words. For example, don't use slashes between words, and don't use the ampersand instead of and.

Incorrect:

Wards/stakes in the United States and Canada submit their forms directly to Church headquarters.
If you have any questions about this application, consult your bishop/branch president.

Correct:

Wards and stakes in the United States and Canada submit their forms directly to Church headquarters.
If you have any questions about this application, consult your bishop or branch president.

When writing about units of the Church, use "wards and stakes" rather than "wards/branches and stakes/districts." Members in branches and districts will understand that the same instruction applies to them.

See Slashes in the Punctuation section for some exceptions.

Please

Generally, instructional text's purpose isn't to persuade, but rather to give steps. Don't use the word please unless you think it necessary when requesting that the user do something.

Correct:

Please send feedback about this system to feedback@churchofjesuschrist.org.

Incorrect:

Please select the checks you want to print.

Should

Avoid saying the user should unless instructing to do something that is strongly recommended.

Never say that the product should do something. This wording conveys doubt about the product's reliability.

Stating the obvious

Avoid writing steps that don't give helpful instruction.

Incorrect:

Type your name in the Name box.

See Forms for guidance on how to treat a set of steps where only a few of the elements on the screen need some explanation.

Don't state things that the product already states, and don't narrate events that will be apparent to the user (see Results of user actions for more on this subject). If the system provides error messages and other feedback, don't restate them in the documentation.

Work with the development team if possible to ensure that system messages meet these standards:

  • They make sense to a nontechnical audience
  • They explain the reason for the message
  • They explain what the user needs to do about it

If giving input on system messages isn't possible, and the messages are inadequate, you may need to provide reference material about them.

Automatically

Avoid the word automatically, as in "The page is automatically updated." In the interest of using active voice, identify the system as the actor when needed.

Unclear abbreviations

If you use an abbreviation, include the full word in parentheses after the abbreviation. On the wiki, you can refer to the abbreviations definition on the Glossary. In general, link to the first instance of the abbreviation on each page, rather than to each instance of the abbreviation.

Articles and content chunking

Articles should have enough information to make sense from any entry point, and they should link to other topics that are related. On the wiki, articles tend to be longer than in traditional help files. This is because wiki articles often stand alone as complete information about a product or subject. However, it's the writer's discretion to determine the length of a topic. You can also break content up over a series of articles all included in the same category.

Writing topic titles and headings

Begin procedural topic titles with a gerund (a verb ending in "ing"). Gerunds are more clear for readers and for translators. Some verbs in imperative form may be mistaken for nouns or other parts of speech.

Correct:

Creating a payment

Incorrect:

Associate managers with their locations
Process Documents

Use no more than three heading levels (the topic title is level one). While writing a topic, if you need to use additional levels, consider breaking the content up into multiple articles.

Capitalization of articles

Article titles and section headings should not use title case. The first letter of the title or heading is capitalized, and proper nouns are capitalized. Other words are not capitalized.

Note: The style guidelines regarding capitalization for articles in the Tech Wiki are different from the rules for articles on LDS.org and other publications, which use title case as outlined in Chicago Manual of Style 8.167. This is because the Tech Wiki follows similar capitalization styles as Wikipedia.


Collections of pages

If you have a collection of pages and need to reflect that they are all part of a group, add the group name in parentheses following the title. For example, if "Design specifications" is one of a dozen project pages, and you want to avoid confusion with other projects that might have similarly titled pages, title your page "Design specifications (Mormon Channel)" -- assuming "Mormon Channel" is your project name.

Avoid using slashes in titles to designate subpages. Adding a slash to a title often converts the page into a subpage, which includes a link back to the base page. Subpages are deactivated in the main namespace of Wikipedia and used only for special namespaces, such as Talk pages and Help pages. The subpage convention is not necessarily a poor idea, but it's not the style used on this wiki because slashes interfere with our translation strategy for pages. Translated pages use a slash in the title followed by a language code to indicate the translated page. If you want to automate a link back to the base page, implement a sidebar to help users navigate content.

Writing lists

Generally, use vertical lists rather than inline lists. Procedures are vertical lists. Using vertical lists when breaking parallel concepts into separate items will visually aid comprehension (for example, when each item is its own sentence or the list consists of three or more items).

Introducing lists

Use a full sentence followed by a colon when introducing a list. List items shouldn't complete a sentence started by the introductory statement. Such introductions and lists are difficult for translators.

Don't indicate the number of items in the list, since that number may change.

See Introducing procedures for the formatting to use for the procedure heading.

List types

In most cases, lists should be vertical.

Ordered Lists

Use ordered lists for procedures or when listed items otherwise follow some logical order.

Use numbers for the first level. Use letters for the second level. If you are writing a procedure that requires a third level, rewrite the procedure so you don't need to go any deeper than a second level.

Unordered lists

Unordered lists are used when order isn't important.

Unordered lists can be used within ordered lists, such as to explain multiple options or concepts within a step.

Inline lists

Use inline lists only when you think ordered or unordered lists wouldn’t make sense or vertical space is limited. The preferred style, however, is to use a vertical list (ordered or unordered). If you would need to add indicators like (1) to an inline list for it to be understood, use a vertical list instead.

Grammar and punctuation with lists

Use sentence case (capitalizing only the first word) for list items unless they are titles.

If the list item is a full sentence, end it with a period. If the item isn’t a full sentence, put no punctuation at the end. (See Chicago Manual of Style 6.127, second sentence.) Keep list items grammatically parallel so all items within a list are punctuated the same way.

Occasionally, only some items will have full-sentence descriptions or elaboration that requires more than once sentence. In this case, end every list item with a period.

Writing procedures

This section addresses general practices for writing procedures.

See Writing topic titles and headings and User interface elements and text for other specific styles.

What should be numbered

A numbered step always indicates an action to be taken. If stating the result of a step or explaining some other event that isn't an action the user performs, place the information in a separate paragraph within that step.

If explaining the immediate results of the overall procedure, do so in a separate, normal paragraph after the end of the procedure. General results or downstream effects of a procedure should be explained in the introductory information so that the user understands the impact of performing the task.

See Writing lists for information about using ordered and unordered lists.

Procedure length

If a procedure takes longer than 12 steps to complete, consider doing the following to reduce the number:

  • Look for places where full steps are actually substeps within what can be considered a miniature procedure. Introduce the substeps in the numbered step, and then use an alpha list for the substeps.
  • Break up the procedure into multiple sections if possible.
  • If all else fails, report the problem to the designer. Usually, if a task requires extensive instructions, it is too complicated, and the design should be simplified.

Introducing procedures

Whenever possible, include an introductory paragraph in procedural topics. In almost all cases, the writer can provide some kind of context (why or when the task would or should be completed) or prerequisites. Keep the introduction focused on the specific task. Use concept topics to give general background information. See Articles and content chunking.

When you have introductory text, use a procedure heading between it and the procedure. Phrase the heading as an infinitive, and use no punctuation at the end. The procedure heading is unique among list introductions.

Example:

To obtain an account 

To introduce a set of substeps within the procedure, use a full sentence. If desired, you may phrase it to indicate what will be accomplished in the substeps.

Example:

Set the start date:

Introducing steps

In general, if you need to direct the user to the element to use, do so at the beginning of the step.

Correct:

In the Comments box, type an explanation for your changes.

Incorrect:

Type an explanation for your changes in the Comments box.

Because these relationships can be changed, avoid referring to user-interface elements' physical relationships with each other ("To the right of the Name box ...") unless doing so is needed for clarity. Instead, refer to just the element.

Steps with multiple actions

It may make sense to combine two brief, consecutive actions into a single step. In this case, follow the Microsoft Manual of Style practice of stating these actions in two independent clauses, separated by a comma with "and then."

Example:

Click Cancel, and then click Yes.

When instructions include using a menu like those in Adobe and pre-2007 Microsoft products, follow one of these examples:

Example 1 (preferred):

In the Internet Explorer menu, click File > Print.

Example 2 (if the menu bar being referred to is already understood):

In the File menu, click Print.

Example 3 (example of more than two menu items):

Click File > New > Document.

Which one you use may depend on the computer experience level of your audience.

If your instructions involve the Ribbon interface from Microsoft Office products from 2007 and later, it is recommended that you use the constructions shown in examples 1 and 3 only if it is already clear you are referring to the ribbon. Otherwise, refer to the tabs in the Ribbon as you would other tabs (see Tabs in the User interface elements and text section).

Single-step procedures

If a procedure consists of one step, format it as a normal paragraph (rather than with a bullet or number).

Example:

To abort the generation process, click Cancel, and then click Yes.

Multiple ways of completing a task or step

If a task can be accomplished in more than one way (meaning the same result will be brought about), provide the shortest set of steps.

If a single step may be completed in multiple ways with different results, format the options with a short introductory step indicating that only one option should be done ("Do one of the following:"). Then list the options as a bulleted list subordinate to the ordered list item.

Don't provide keyboard shortcuts unless at least one of the following applies:

  • The keyboard shortcut is the only way to complete an action.
  • Your audience has sufficient computer expertise and prefers shortcuts.
  • Your content includes a set of steps for advanced users.

Conditional steps

Some procedures may have a step that will be performed differently depending on a variation of the task, circumstances, or preferences. For example, one step may involve selecting either Yes or No. These steps usually begin with an if statement.

When multiple options are available, introduce conditional steps with "Do one of the following:" or another full sentence as the main step. Then format the conditional steps with a subordinate bulleted list.

In general, order the conditions logically (such as Yes before No, to match the choices in the interface, or most common to least common). However, if only two conditions exist and one is much longer than the other, place the shorter item first so that it's more noticeable as a separate item.

Correct:

If this event doesn't require any resources, select None.
If this event does require resources, identify them:
Select Specify.
Select the check box for each required resource.
Click Add.

Incorrect:

If this event does require resources, identify them:
Select Specify.
Select the check box for each required resource.
Click Add.
If this event doesn't require any resources, select None.

Optional Steps

Indicate an optional step by doing the following:

3. Optional. Select the Urgent check box.

Examples

If providing an example of user input after a step, place it after the step. This makes it clear whether closing punctuation must be part of the user input.

Example:

Type your membership record number with 13 characters, including hyphens.

Example: 000-1234-5678

Additional information, notes, and warnings

Include non-instructional information, such as notes and warnings, only when it directly impacts a step or the procedure as a whole. In the flow of the topic, place the information where it is most relevant and timely.

If you want to draw attention to the information, use a note format:

  • Note: Use when the information departs somewhat from the subject of the topic.
  • Important: Use when the information is related to the topic at hand and the user should be aware of the information, such as when failure to take notice or comply could lead to inconvenience.
  • Warning: Use only when the information is critical and failure to take notice or comply could lead to data loss or hardware damage.

Results of user actions

Avoid stating what happens as the result of an action. Usually, the result of the action is apparent, such as a new page appearing or information being saved, particularly if the user clicked a button or link whose text indicates what will happen (for example: "5. Click Save. The information is saved."). If you are integrated in the development team, encourage the interaction designers and developers to include system feedback that makes clear what is happening (such as Loading modals in IxF applications). In procedures, state the result of a step only if the result isn't clear.

If a new window or modal appears, continue providing instructions. If you think it will be unclear that the user should interact with the new window, introduce the first step with something like "In the File Download dialog box."

If explaining the immediate results of the overall procedure, do so in a separate, normal paragraph after the end of the procedure. General results or downstream effects of a procedure should be explained in the introductory information so that the user understands the impact of performing the task.

Forms

If your procedure involves completing a form and not all elements need explanation, write an inclusive step such as "Complete the form." If some aspects of the form need explanation, add a bulleted sublist explaining these items. Introduce the list with a sentence like "Note the following items:"

Avoid writing steps like "Type your name in the Name box."

User interface elements and text

Follow this style guide both in technical documents and when providing feedback to development teams or directly editing interface text in an electronic file.

Case

Use title case for buttons, menu items, and so on.

Exception: Use sentence case for radio button and check box text when the items consist of full sentences. If only one item is a full sentence, all items should use sentence case for consistency.

Sometimes, interaction designers or developers like to lowercase every word. Unless they have a practical reason for no capitalization, emphasize the importance of following Church style for consistency and a professional look.

Complete sentences

UI elements and dynamic data fields should be located only at the beginning or end of text. Inserting these items in the middle of text is problematic for translators.

Incorrect element placement:

Patron should arrive [x] before appointment

Correct:

Time the patron should arrive before appointment [x]

Incorrect dynamic data field placement:

You have {x} items to complete.

Correct:

Items to complete: {x}

Correct:

Send feedback to tech@churchofjesuschrist.org

Become familiar with Chapter 10 of the Church style guide, which treats computer and Internet terms. For additional terms, see Technical terms and usage.

Some entries in this section refer to the Interaction Framework (IxF), a set of predefined layouts created by ICS interaction designers and used in some web applications.

Using descriptors

Some procedure steps use a descriptor, which is an interface element identifier following the element label. For example, in the text "Save button," button is the descriptor.

Use descriptors only for the following elements:

  • Tabs
  • Boxes
  • Menus
  • Keys (on a keyboard)

Exception: Include a descriptor if confusion may result from leaving it out.

Label text

Use bold formatting for label text when identifying an element that the user interacts with.

Example:

When finished, click Save.

Pages, screens, and sections

Title case is recommended for page or screen titles and for headings of interface sections, such as sections of a form. Use title case when referring to page or screen titles, and use no quotation marks or other additional punctuation. When referring to sections, use the same case that is used in the interface, and bold formatting for the title text to set it off from the rest of the text (which provides clarity when the section is in sentence case). Use no quotation marks or other additional punctuation.

When writing about websites, refer to pages. With desktop and mobile applications, refer to screens. If writing about a web application, consider your audience. Use the term that will be most clear, and be consistent throughout your project. For example, an audience accustomed to desktop applications may think of computer programs in terms of screens, while frequent Internet users may think of web applications in terms of pages.

Statuses

When referring to a named status of something in a system, emphasize it with italics.

Example:

When the missionary's MTC date has arrived, the status changes to Active.

Clicking

Instruct users to click something when referring to pressing the left mouse button to initiate an action.

Do not write click on. This rule applies also to double-click and right-click.

Selecting

Instruct users to select when the item is in a list, such as a drop-down list, a checklist, or a set of radio buttons.

Typing vs. entering

Text is typed into a field, not entered. However, if you are referring to a form as a whole with multiple elements, it is appropriate to use enter, as in "enter the requested information."

If instructions tell the user exactly what to type in a field, use <pre> tags to set off the text. If the text to be inputted comes at the end of the step, put it on a new line (introduced by a colon) so that it is clear what should be typed.

Example:

In the Path box, type the following: 
C:/My Documents/Stuff/2011-statement.docx

Note: Do not use this style when the exact text to be typed isn't specified. For example, the instruction "Type your LDS Account username and password" does not use this style because the user name and password will be different for everyone.


Keyboard keys and combinations

Use bold formatting when referring to keyboard commands. The verb is to press. Use the case on the key itself (not all caps as in Microsoft Manual of Style), and use the key descriptor.

Example:

Type your name, and then press the Enter key.

When writing a key combination, use the plus sign without spaces between each key name. Format only the key names in bold, not the plus sign. Don't use a descriptor.

Example:

To open the Find dialog box, press Ctrl+F.

According to the Microsoft Manual of Style, refer to key combinations as keyboard shortcuts (p. 288).

See Multiple ways of completing a task or step in the Writing procedures section.

Touchscreens

The touchscreen equivalent of a click is a tap. The equivalent of a double-click is a double-tap.

Use these terms for other gestures:

  • Drag: Sliding the fingertip slowly across the screen
  • Swipe: Sliding the fingertip quickly and lightly across the screen
  • Flick: The same as a swipe except a shorter movement
  • Pinch: Touching the screen with two fingers (usually the thumb and forefinger) and bringing them together
  • Press and hold: Touching the screen longer than with a tap

Example:

To view the Contact menu, press and hold a person's name.

Example:

Pinch the screen to see a wider area of the map.

Various terms appear on the Internet for the opposite gesture of pinch. The most concise is spread, which comes from the Touch Gesture Reference Guide. Because there is no standard term for this gesture and using spread alone may be unclear to the reader, write "spread your fingers on the screen."

Example:

Spread your fingers on the screen to zoom in and enlarge the text.

Elements

The following items discuss how to handle specific user interface elements. When it comes to descriptors, if no rule is provided, refer to Using descriptors.

Headers

Most software has some kind of banner or bar across the top of the screen. Refer to this as the header.

When referring to the top bar in an IxF layout, use main menu.

Note: The label of a table column is called the column head, not the column header (Chicago Manual of Style 13.3).


Subheaders

In some IxF layouts, a secondary bar runs beneath the main menu and contains navigation options. Refer to this bar as the submenu.

Tabs

Use the tab descriptor when instructing the user to click a tab.

In procedures, instruct the user to click the tab and then in subsequent steps to interact with the elements.

If referring to content or elements on a page viewed by clicking a tab, such as in an overview, write under, not on, the tab. The only things on the tabs themselves are text and sometimes icons. Referring to the elements as on the tab may be unclear for nontechnical audiences.

Example:

Under the Temple Profile tab, you manage the temple's basic information.

Note: In IxF, tabs don't look like traditional folder tabs. They look more like a row of contiguous buttons.


Subtabs

Some applications have a row of links displayed beneath the tabs, and they change based on the tab selected. Refer to each of these links as a subtab.

Menus, menu options, and the ribbon

When writing about menus or the Microsoft Office Ribbon, the user clicks an option in the menu or Ribbon or selects an option from the menu or Ribbon. Regarding in vs. from, choose one and be consistent within your project.

Breadcrumb trails

A breadcrumb trail is a row of links showing the path that the user took from the home page or the current page’s place in the site or application structure. Refer to the collection of links as the breadcrumb trail. If you need to describe the function of the individual items, refer to them as breadcrumbs.

Do not use breadcrumb as a descriptor.

Correct:

Click Home in the breadcrumb trail.

Incorrect:

Click the Home breadcrumb.

Note: If your audience is inexperienced, you may need to provide material explaining the breadcrumb trail concept.


IxF panels

IxF has layouts that separate the user interface into multiple sections. If referring to these sections, use the word panel. Name the panel when referring to it if it has a title. Otherwise, refer to location, as in left panel and right panel.

Drop-down Boxes and Combo Boxes

Refer to drop-down and combo boxes by their labels with just box as the descriptor.

For drop-down boxes, use wording like this:

Click the Type box, and then select Ecclesiastical.

Combo boxes provide the ability to either type a value or select a predefined value. If you need to leave the value entered up to the user, use wording like this:

Click the Points box, and then type or select a value.

If your audience isn't familiar with computers and you need to write some content about basic UI elements, refer to these as a "drop-down box" for that purpose only. The above practices apply in the rest of the content. Do not use any of these terms:

  • drop-down menu
  • pull-down menu
  • picklist
  • drop-down combo box

Text fields

Field is considered by some to be a technical term. Generally, use box unless you are writing for a technical audience and you think field will be more clear. Whichever term you use, be consistent throughout your project.

Check boxes

Select a check box to place a check mark. Clear a check box to remove the check mark. Use the label and the check box descriptor.

Example:

Select the Stakes check box.

Sometimes, check box labels are long. For example, the label may be a full sentence, or it may be located next to a lengthy statement where the user is agreeing to something. In these cases, the normal approach may not work. Instead, follow the examples below.

Examples:

Select the check box labeled I do not have an LDS Account.
Select the check box indicating that you have performed the necessary steps and agree to the terms.

Radio buttons

Select a radio button option. Name the button's label, and use no descriptor.

Action buttons

Click an action button. Use no descriptor.

Example:

When you have completed the form, click Save.

Links

Click a link. Use no descriptor.

Clickable icons

With accompanying text: If a clickable icon has a label, use that label when referring to the icon, followed by a sample of the icon. Use no descriptor.

Without accompanying text: Use the same format as for icons with text, but use the icon's alt text as the label text. Use no descriptor.

Dialog boxes, javaScript Alerts, and modal windows

Unless needed for clarity, don't refer to the titles of dialog boxes. Usually it is sufficient to continue the procedure without explaining where to interact, since dialog boxes take the focus of the page or screen. Further, it is usually unnecessary to call out the fact that a confirmation box appears, and the action in the confirmation dialog can be included in the previous step.

Correct:

4. Click Delete, and then click Yes.

Incorrect:

4. Click Delete.
5. In the confirmation dialog, click Yes.

If referring to the title for clarity, use the dialog box descriptor.

In general, it should be unnecessary to discuss JavaScript alerts. Alerts and confirmation dialog boxes are system feedback that is self-documenting.

A modal window is basically a web version of a dialog box, so follow the rules above. Do not use the term pop-up window or pop-up, which are separate browser windows typically used for ads on websites.

Tables

The heading over a table column is called a column head (see Chicago Manual of Style 13.3).

Technical terms and usage

Generally avoid technical terms like algorithm and logic unless you are writing for a technical audience.

See also Technical jargon and alternatives, User interface elements and text, and Chapter 10 of the Church style guide.

data

Avoid using data as the subject of a sentence, since people can't agree on whether it takes a singular or plural verb. Use the word information as the subject when possible.

dimensions

To set off width and height, use the multiplication sign (Alt+0215) with no spaces. Include the measurement (usually pixels) if it isn’t clear.

Example:

1024×768

Do not use the term aspect ratio if instructing the user how to change an object's size unless you are writing for a technical audience. Refer to the object's proportions staying the same or similar wording.

e-mail

Hyphenated according to Merriam-Webster. Can be used as a noun, but don’t use as a verb (the only definitions in Merriam-Webster are nouns). Write "send an e-mail" or "send by e-mail" instead.

file extensions

Lower case with a period.

Example:

Save in .jpg format.

Exception: It's all right to refer to Portable Document Format files as "PDF files," but not as just "PDFs." It is somewhat redundant to write, "Save in .pdf format," so it is better to write, "Save as a PDF file."

file size

Treat the same way as acronyms, spelling the term out in the first mention in the topic, followed by the abbreviation in parentheses. If used again in the topic, abbreviate the file size using all caps, and include a space before the size.

Examples:

The size of uploaded files is limited to 2 megabytes (MB).
12 MB

Exception: If your entire audience is technical and will understand the abbreviation, it is acceptable to use just the abbreviation throughout your project. Otherwise, if you have any doubt as to whether some of your audience will need help understanding the abbreviation, follow the above information.

home page

Two words.

install

Use only as a verb, not a noun. For the noun, use installation.

Internet

Capitalize. There is only one, making it a proper noun.

If instructing users to open an Internet connection, write "connect to the Internet," not "log on to the Internet."

intranet

Not a proper noun. Do not capitalize in body text.

legacy

Generally refers to a system being replaced or something that is out of date or defunct. Use only when writing for technical audiences.

log in, log out

Do not use these terms. See sign in, sign out.

log on, log off

Use only when referring to starting a session on a computer or network (for example, you log on to the Church desktop). The need to use these terms is extremely rare.

Login and logout are incorrect.

For opening an Internet connection, use "connect to the Internet," not "log on to the Internet."

See also sign in, sign out.

Meetinghouse

The word "meetinghouse" should not generally be capitalized when it is simply referring to a building in which members meet. However, the word can be used in proper noun phrases such as Meetinghouse Webcast Communicator or Meetinghouse Internet; in such cases, the word "Meetinghouse" should be capitalized, since those specific technologies are appropriately referenced as proper nouns.

mobile

Use mobile device to refer to phones and other handheld devices in general. If referring just to phones, use mobile phone.

modal windows

Refer to an HTML modal window as a dialog box unless your audience consists exclusively of web designers and developers. General audiences do not understand what a modal window is.

mouse, mouse pointer

The mouse is the device used to move the mouse pointer. Do not confuse the two in your writing.

Correct:

Move your mouse pointer to the text box.

Incorrect:

Move your mouse to the text box.

navigation

By itself, the word navigate may not be meaningful to less technical audiences if used alone. Use navigate or navigation only for technical audiences or if adding "the system" or "the application" to form a phrase.

opt in, opt out

Do not hyphenate these terms.

parentheses

Plural. The singular is parenthesis, as in "Be sure to include the closing parenthesis."

set up, setup

Two words as a verb, one word as an adjective or noun.

sign in, sign out

Use this wording for entering an application or website that requires a username and password. These are never one word.

Someone signs in to an application, not signs into it. If possible, see to it that Church applications and sites use this wording instead of log in and log out.

sign up

Avoid this phrase. Use register.

Example:

Register for an LDS Account.

solution

Avoid this word in end-user documentation when referring to a product. Use system, application, or program instead. Solution isn’t a meaningful term for nontechnical audiences.

username

One word. If the field in the interface uses two words, try to have the interaction designers or developers change it to one word. If this fails, refer to the box with two words to match what the user sees on the screen.

website

One word per Chicago Manual of Style.

web page

Two words per Merriam-Webster’s and CMOS.

Using images

When writing conceptual information, think about how the concepts may be illustrated in a diagram or other image. Images can often convey information more clearly than text.

If your content will be translated, consider ways to avoid including text in the image, or set up the text in a way that it can be exported quickly and reimported once translated. Making text part of the image file adds to the time you need to prepare translated material.

Do not lay out the text rigidly for English. Instead, leave white space.

Color

Avoid using color as the primary way of conveying information. Instead, use shades of gray, patterns (such as hatching), or callouts. It is acceptable to use color as a secondary or tertiary means of conveying information and to add visual interest.

Do not use neon, pastel, or iridescent colors, which are difficult for colorblind people to see. (For the sake of good taste, it's probably best to avoid neon and iridescent colors anyway.) For a list of pastel hexadecimal values, see http://www.hitmill.com/html/pastels.html and http://www.hitmill.com/html/pastels2.html.

Screenshots

In general, use screenshots only when the user might otherwise be confused in following your instructions. Do not include a screenshot between each step.

In most cases, well-written and well-structured content is sufficient for clearly communicating user actions. Screenshots create many hidden costs that often exceed the value they were intended to provide. For example, each time the captured screen changes, a new screenshot is usually needed, increasing maintenance effort and cost.

Additionally, if translation is required, you must capture each screen in each of the languages to which your content is to be translated. This often requires accessing the software in each language, setting up the same user scenarios for each language, and then capturing screens across all languages. Further, if changes occur, you will likely have to repeat this process multiple times.

Useful exceptions might include these cases:

  • Overviews of a user interface describing key navigation components
  • Complicated screens or dialog boxes where a screenshot with callouts could provide a useful reference

Diagrams, text, and callouts

Unlike screenshots, diagrams typically don't document the user interface directly. They can provide valuable insight for larger procedures, workflows, and business processes.

Be aware that including texts within diagrams creates similar issues when translation is a requirement. One recommendation is to keep text within the diagram to a minimum, or avoid making text a part of the diagram itself (for example, put text in a caption outside the image). Some tools can overcome this issue by allowing translation teams to extract the text from the image, translate, and then reinsert the translated text.

If text is needed in the image and it will be translated, do not lay out the text rigidly for English. Leave white space.

If separating callout text from the image, use numbers (not letters) to label the elements in the image.

Alt text

Always include alt text for images that will be viewed in a web format (potentially, this is all images). Alt text shouldn't describe what the image is. Instead, it should provide the information that the image is intended to convey.

If an image conveys a set of data, describe the main takeaways in the alt text.

Image licensing

Ensure that you have a license to use all images, and track the licensing information in a separate document.

Software created by the Church must be approved by Correlation before they will approve screenshots and videos of such software. This approval requires submission of the licenses for the code libraries used in the product. Correlation has an existing contract for using screenshots of Microsoft Windows and Microsoft Office products.

Referring to the Church

Church name

Be familiar with the policies governing use of the Church's name and logotype. The Church's full name always begins with a capital "The," even in the middle of a sentence. The Church’s name needs no special formatting such as quotation marks or italics.

Incorrect:

The church accepts charitable donations:

Correct:

The Church accepts charitable donations:

Note: "Church" should not be used when "Church headquarters" or CHQ would be more appropriate.


The Church logotype is set in the Deseret typeface. In your documents, do not use typefaces that resemble Deseret, such as Trajan and Trajan Pro. Using typefaces similar to Deseret weakens the Church's brand.

Church headquarters

Church headquarters should only be referenced as Church headquarters or CHQ and not Salt Lake. However, in most cases it is more appropriate to refer to the Administration office, since units outside of the United States and Canada do not communicate most administrative matters directly to CHQ, but rather to an Area administration office.

Salt Lake

Articles should not reference Salt Lake in place of Church headquarters. While Church headquarters is located in Salt Lake City, the distinction between the city and the organization should be made by referencing Church headquarters or CHQ instead of Salt Lake.

Church handbooks

The Church handbooks may be referenced generically as "Church handbooks." Specific references should detail the book (Handbook 1: Stake Presidents and Bishops or Handbook 2: Administering the Church), the publication year in square brackets, and the section number(s). Do not use page numbers for references (which make no sense for the online version of the handbooks). For example:

Handbook 1: Stake Presidents and Bishops [2010], 16.7.

Handbook 2: Administering the Church is published online at LDS.org, so it can be helpful to provide links to specific sections. For example:

Handbook 2: Administering the Church [2010], 13.4.

LDS Technology Website

The Church's technology website should be referenced as Tech, or by its full name, "Technology Website." The entire URL is not needed. An external link should always be included at least once in the article. If referencing material on Tech, contributors are encouraged to consider whether a direct link to the material, thread, post, or webpage is more appropriate than a link to the home page of Tech with navigation instructions. The {{Tech}} template can be used for references to threads and posts on the Tech forums.

Clerk and Technology Support

The Church's website dedicated to clerks and technology support should be referenced as Clerk and Technology Support. The entire URL is not needed. An external link should always be included at least once in the article. If referencing material on Clerk and Technology Support, contributors are encouraged to consider whether a direct link to the material or webpage is more appropriate than a link to the home page of Clerk and Technology Support with navigation instructions.

LDS.org

The Church's main website should be referenced as LDS.org. The entire URL is not needed. An external link should always be included at least once in the article. If referencing material on LDS.org, contributors are encouraged to consider whether a direct link to the material or webpage is more appropriate than a link to the home page of LDS.org with navigation instructions.

Church units

This section covers referencing the different units of the Church: stakes, wards, districts, and branches. The examples below show the proper use of "stake" but the principle is the same across all the units of the Church.

Incorrect (generic):

The Stake should record Melchizedek Priesthood ordinations.:

Correct (generic):

The stake should record Melchizedek Priesthood ordinations.:

Correct (specific):

The Frederick Maryland Stake covers most of Frederick County, Maryland.:

Roles and callings

Refer to people by their roles or callings whenever possible. Avoid the word user unless no alternative makes sense. If a bishop uses an application, refer to him as a bishop instead of a user. Often, even the words person and individual can be used instead of user.

If writing a sentence where you are inclined to refer to users, consider whether it may be appropriately rewritten in second person.

Incorrect:

Users of this system are required to keep all information confidential.

Correct:

You are required to keep all information in this system confidential.

Refer to Chapters 8 and 14 of the Church style guide for details on the treatment of callings. The overall guideline for capitalization is that a calling is capitalized only when someone holds it by virtue of being a General Authority (Apostle, Seventy, Area President). However, when addressing or talking about a specific person using the title, capitalize the calling.

Example:

On Thursday, Bishop Young attended a meeting with the other bishops in the stake.

Note: Do not capitalize Church unit terms unless stating the full name of the unit. The word "stake" in the above example would be capitalized only if a specific stake was named, as in, "Bishop Young attended a meeting with the other bishops in the Granite Peak Stake."


Certain callings should not be used as titles preceding a person's name, such as Apostle ("Elder") and patriarch ("Brother").

Plurality and gender neutrality

Do not use they or them to refer to an individual. Whenever possible, pluralize the sentence to avoid having to use "him or her" or corresponding phrases, which are wordy and problematic for translators. Pluralizing the sentence allows legitimate use of plural objective pronouns. Sometimes, you can rewrite such sentences to eliminate the problem entirely.

Incorrect:

A missionary needs an LDS Account before they can sign in.
A missionary needs an LDS Account before he or she can sign in.

Correct:

Missionaries need an LDS Account before they can sign in.
A missionary must have an LDS Account to sign in.

The next-best practice is to alternate between masculine and feminine pronouns (but not while talking about the same person or role, which causes confusion and looks like an editing error). Exclusively using one gender may be seen as sexist and should be avoided.

Exception: In a number of cases, masculine pronouns can appropriately be used without risk of sounding sexist. General Authorities, stake presidents, bishops, and other priesthood callings are always occupied by men, so the following text is correct: "When the stake president has completed his checklist, he submits the recommendation forms to Church headquarters."

Punctuation

This section explains whether and how to use certain punctuation and how to avoid common mistakes.

Commas

Include a comma between independent clauses separated by a conjunction.

A possible exception is to omit the comma between very short independent clauses (Chicago Manual of Style 6.32), but be consistent within your project.

See Steps with multiple actions in [#Writing procedures|Writing procedures]].

Use a serial comma in inline lists with three or more items (Chicago Manual of Style 6.33). See also Writing lists.

Separators

In situations where words or phrases need a separator, such as in a title, use one of the following:

  • Colon
  • Em dash (Alt+0151) with no spaces
  • Comma
  • Bullet (Alt+7)

The pipe character is okay if you have a specific reason for using it, but it is not recommended, since its main use has traditionally been to separate links on a web page and could give the wrong impression.

Do not use hyphens or en dashes as separators unless you are naming something in the interface that does so. If you give input to designers on prototype text or edit it yourself, use one of the separators in the above list.

Correct:

Vendors: Selecting a Vendor

Incorrect:

Vendors - Selecting a Vendor

Slashes

Don't use slashes unless they are specifically required by the content, such as in file paths, URLs, or terms like read/write permission.

Never use a slash in place of a conjunction, since it leaves in doubt which conjunction is meant. Avoid the conjunction combination and/or because it presents a problem for translation; instead, rewrite the sentence to make the meaning clear. In many cases, or suffices.

Correct:

If you need to view or change the item's information, click Details.

Incorrect:

If you need to view and/or change the item's information, click Details.

Apostrophes

Do not include an apostrophe before the s in pluralized acronyms or in decades unless the century is omitted, in which case the apostrophe precedes the number.

Examples:

IOSs, 1980s, ‘90s

Hyphens

Do not use hyphens as separators unless you are naming something in the interface that does so.

Be familiar with proper use of hyphens. See Chicago Manual of Style 5.92 and 5.93 for rules about hyphens in phrasal adjectives.

Exclamation marks

Use exclamation marks sparingly. They are usually not appropriate for instructional text.

Don't use exclamation points to convey enthusiasm or excitement. If such a tone is needed, use word choice to convey it.

Use warning styling to indicate urgent text, not exclamation marks, since the purpose of an exclamation mark can be ambiguous.

En dashes (Alt+0150)

Use only in numeric ranges, such as dates, or when needed in compounds (see Chicago Manual of Style 6.85). Do not add spaces around the dash. Do not use an en dash preceding a quote attribution (use an em dash instead).

Em dashes (Alt+0151)

Avoid using em dashes except as a separator. Use an em dash also to indicate a quote attribution if the quote isn't inline.

Example:

"As we bear His holy priesthood worthily, we will be victorious."

—President Thomas S. Monson