Skip to main content
Contributor's Guide

Style guide for NetApp docs

Contributors netapp-jsnyder netapp-dbagwell netapp-bcammett amgrissino netapp-ssmith
PDFs

Our style is conversational and empathetic, but we stay professional and get to the point. Follow these guidelines when writing content for NetApp docs.

Write conversationally

Write like you speak when you're explaining something to a professional colleague. Writing in a conversational tone helps you connect with your audience.

Too formal Too casual Our style

If you experience issues with BlueXP tiering, you can view the health status on the Cluster Dashboard to determine why the error occurred. The health reflects the status of the ONTAP system and the Service Connector.

It's no fun when failures happen. Don't worry though, just check out the Cluster Dashboard to see what happened and what's affected.

When there's a failure, BlueXP tiering displays a "Failed" health status on the Cluster Dashboard. View the status to get information about the failure.

Before you can provision storage, you must discover your ONTAP cluster from BlueXP. After discovery is complete, you must open the working environment to provision storage.

All you do is first discover your ONTAP cluster from BlueXP, then open the working environment to start provisioning storage. Easy!

After you discover your ONTAP cluster from BlueXP, open the working environment to provision storage.

When the Setup wizard starts, follow the instructions in the wizard to set up the node and join it to the cluster. The following steps walk you through the steps in the wizard.

The Setup wizard appears (almost like magic), to guide you through the simple process of setting up the node and joining it to the cluster.

Follow the instructions in the Setup wizard to set up the node and join it to the cluster.

You can choose from among multiple content format types to install and set up your new system. Each format type provides complete instructions. Choose the format type that most closely matches the way you like to learn.

How do you want to set up and install your system? We provide instructions in multiple content format types, but only you know how you like to learn.

Choose a content format type to guide you through installing and setting up your system.

Use contractions

Contractions reinforce a conversational tone, and many contractions are easy to understand and translate.

Expand to learn more

  • Use contractions like these, which are easy to understand and translate:

    aren't

    you're

    isn't

    we're

    wasn't

    it's

    weren't

    let's

    didn't

    we'll (if future tense is required)

    doesn't

    won't (if future tense is required)

    don't

    you'll (if future tense is required)

  • Don't use contractions like these, which are hard to understand and translate:

    would've

    should've

    wouldn't've

    shouldn't've

    could've

    couldn't've

Write simply

Avoid big and confusing words. Keep it simple. You're explaining something to a professional colleague, not showing off your vocabulary.

Rather than this: "Dissociate the user from your NetApp Cloud Central account."

Do this: "Remove the user from your NetApp Cloud Central account."

Write minimally

Short, simple sentences make content easier to read or scan. It's okay to use a longer sentence every now and then but follow it with a shorter one. Like this.

Rather than this: "To replicate data between a Cloud Volumes ONTAP system in AWS and ONTAP systems in other networks, you must have a VPN connection between the Amazon VPC and the other network—for example, an Azure VNet or your corporate network."

Do this: "Data replication between networks requires connection through a VPN. For example, between your Amazon VPC and your corporate network or between AWS and Azure."

Ask yourself the following:

  • Do users need this content at this place, at this time?

  • Does the user interface already guide the user well enough? If it doesn't, what additional guidance can be added succinctly?

  • Can I present the content in fewer words without sounding too formal or too casual?

  • Can I shorten or simplify a long sentence or break it into two or more sentences?

  • Can I use a list to make the content more scannable?

  • Can I use a graphic to augment or replace a block of text?

Write actively

Avoiding passive voice is a standard rule for tech writing, but it's especially important to use active voice when you want to sound conversational.

Active voice

Use active voice so that the subject of the sentence performs the verb's action. This typically means that the verb follows the subject of the sentence. Active voice keeps writing crisp and clear. Use active voice and address users directly as "you" unless you have a specific reason to use passive voice.

Here are some examples of good active voice writing. Write like this:

  • Provide the required permissions before you deploy your first cluster.

  • If you shut down the system improperly the interface displays a warning message.

  • NetApp received the contract.

Passive voice

In passive voice, the doer of the action is unclear:

  • A warning message is displayed if the system is shut down improperly.

  • NetApp was awarded the contract.

Use passive voice when:

  • You don't know who or what performed the action.

  • You want to avoid blaming users for the results of an action.

  • You can't write around it, such as for some prerequisite information.

Imperative mood

Use imperative mood for steps, directives, requests, and headings for lists of user actions:

  • "On the Working Environments page, click Discover and select ONTAP Cluster."

  • "Rotate the cam handle so that it is flush against the power supply."

Consider using imperative voice to replace passive voice:

Rather than this: "The required permissions must be provided before you deploy your first cluster."

Do this: "Provide the required permissions before you deploy your first cluster."

Avoid using imperative voice to embed steps in conceptual and reference information.

For additional verb conventions, see:

Write consistent content

"Write like you speak when you're explaining something to a professional colleague" means something different to everyone. Our professional yet conversational style helps connect us to users and increases the frequency of minor inconsistencies among multiple contributing authors:

  • Focus on making the content clear and easy to use. If all content is clear and easy to use, minor inconsistencies don't matter.

  • Be consistent within the page you're writing.

  • Always follow the guidelines in Write for a global audience.

Use inclusive language

NetApp believes that its product documentation should not contain discriminatory, exclusive language. The words that we use can make a difference between forging a positive relationship with our customers or alienating them. Especially with written words, impact is more important than intent.

As you create content for NetApp products, avoid language that can be interpreted as degrading, racist, sexist, or otherwise oppressive. Instead, use language that is accessible and welcoming to everyone who needs to use the documentation. For example, instead of "master/slave" use "primary/secondary."

Use people-first language where we refer first to the person, followed by the disability.

Don't use he, him, his, she, her, or hers in generic references. Instead:

  • Rewrite the sentence to use the second person (you).

  • Rewrite the sentence to have a plural noun and pronoun.

  • Use "the" or "a" instead of a pronoun (for example, "the document").

  • Refer to a person's role (for example, reader, employee, customer, or client).

  • Use the term "person" or "individual".

Examples of words and phrases that are considered inclusive or exclusive

Inclusive examples Exclusive examples

Primary/secondary

Master/slave

Allowed list

Whitelist

Blocked list

Blacklist

Stop

Kill

Stop responding

Hang

End or Cancel

Abort

Person hour

Man hour

Developers need access to servers in their development environments, but they don't need access to the servers in Azure.

A developer needs access to servers in his development environment, but he doesn't need access to servers in Azure.

Person who is blind

Sight-impaired

Person with low vision

Vision-impaired

Get to the point

Each page should start with what's most important to the user. We need to find out what the user is trying to do and focus on helping them achieve that goal. We should also add keywords at the beginning of the sentence to improve scan ability.

Follow these general sentence guidelines:

  • Be precise.

  • Avoid filler words.

  • Be short.

  • Use formatted text or bulleted lists to highlight key points.

Examples of getting to the point

Good examples Bad examples

If your business has strict security policies, use data-in-flight encryption to sync data between NFS servers in different networks.

Cloud Sync can sync data from one NFS server to another NFS server using data-in-flight encryption. Encrypting the data can help if you have strict security policies for transferring data over networks.

Save time by creating a document template that includes the styles, formats, and page layouts you use most often. Then use the template whenever you create a new document.

Templates provide a starting point for creating new documents. A template can include the styles, formats, and page layouts you use frequently. Consider creating a template if you often use the same page layout and style for documents.

Astra Control provides three operational modes that you can assign to your users to carefully control access between Astra Control and your cloud environment.

Astra Control enables you to assign one of three operational modes for users in your AWS accounts. The modes allow you to carefully control access between Astra Control and your cloud estate based on your IT policies.

Use lots of visuals

Most people are visual learners. Use videos, diagrams, and screenshots to improve learning, break up blocks of text, and provide a visual cue to users as to where they are in the task instructions.

  • Include a lead-in sentence that describes the image that follows: "The following illustration shows the AC power supply LEDs on the back panel."

  • Refer to the location of the illustration as "following" or "preceding," not "above" or "below."

  • Use alt text on embedded visuals.

  • If the visual pertains to a step, include the visual right after the step and indented to align with the step number.

Best practices on screenshots:

  • Include no more than 5 screenshots per task.

  • Don't include text in a screenshot. Use numbered callouts instead.

  • Be judicious with the screenshots you choose to include. Screenshots can go out of date quickly.

Best practices on videos or animations:

  • Videos should be under 5 minutes in length.

Examples

Create scannable content

Help readers find content quickly by organizing text under section headings and by using lists and tables. Headings, sentences, and paragraphs should be short and easy to read. The most important information should be provided first.

Examples

Create workflows that help users achieve their goal

Users read our content to accomplish a specific goal. Users want to find the content they need, accomplish their goals, and go home to their families. Our job is not to document products or features. Our job is to document user goals. Workflows are the most direct way to help users accomplish their goals.

A workflow is a series of steps or subtasks that describes how to achieve a user goal. The scope of a workflow is a complete goal.

For example, the steps to create a volume would not be a workflow, because creating a volume in itself is not a complete goal. The steps to make storage available to an ESX server could be a workflow. The steps would include not only creating a volume, but exporting the volume, setting any necessary permissions, creating a network interface, and so on.

Workflows are derived from customer use cases. A workflow shows only the one best way to achieve the goal.

Organize content based on the user's goal

Help users find information quickly by organizing content based on the goal that the user is trying to achieve. This standard applies to the table of contents (navigation) for a documentation site, as well as the individual pages that appear on the site.

Organize content as follows:

The first entry in the left-hand navigation (high level)

Organize content around the goals that the user is trying to achieve. For example, the first entry in the navigation for the site might be "Get started" or "Protect data."

The second-level entries in the navigation for the documentation site (medium level)

Organize content around the broad tasks that compose the goals.

For example, the "Get started" section might include the following pages:

  • Prepare for installation

  • Install and set up <product name>

  • Set up licensing

  • What you can do next

Individual pages (detailed level)

On each page, organize the content around the individual tasks that compose the broad tasks. For example, the content that users need to prepare for installation or to set up disaster recovery.

A page can describe a single task or multiple tasks. If there are multiple tasks, they should be described in separate sections on the page. Each section should focus on a single learning or doing aspect of the broad task. This might include some conceptual and reference-based information that's required to complete the task.

Write for a global audience

Our documentation is read by many users whose primary language isn't English. We translate our content into other languages using Neural Machine Translation tools or human translation. To support our global audience, we write content that is easy to read and easy to translate.

Follow these guidelines to write for a global audience:

  • Write short, simple sentences.

  • Use standard grammar and punctuation.

  • Use one word for one meaning and one meaning for one word.

  • Use common contractions.

  • Use graphics to clarify or replace text.

  • Avoid embedding text in graphics.

  • Avoid having three or more nouns in a string.

  • Avoid unclear antecedents.

  • Avoid jargon, colloquialisms, and metaphors.

  • Avoid nontechnical examples.

  • Avoid using hard returns and spacing.

  • Don't use humor or irony.

  • Don't use discriminatory content.

  • Don't use gender-biased language unless you're writing for a specific persona.

A to Z guidelines

acronyms and abbreviations

Use well-known acronyms and abbreviations for familiarity but avoid obscure ones that might negatively affect clarity and findability. For additional conventions for acronyms and abbreviations, see the Microsoft Writing Style Guide.

active voice (versus passive voice)

Refer to Write actively.

admonitions

Admonitions are a powerful tool when used correctly. They can draw attention to important information, provide helpful tips, or warn users about potential hazards. When overused, they lose their impact and can lead to user fatigue. Here are some guidelines to ensure the effective use of admonitions.

Use the following labels to separate admonitions from the main content flow:

  • NOTE
    Use NOTE to highlight important information that must stand out from the rest of the text. However, avoid using NOTE for "nice to know" information that isn't essential for users to understand or complete a task. The purpose of a NOTE is to draw the reader's attention to critical points that they might otherwise overlook.

  • TIP
    TIPs should be used sparingly, if at all, as our policy is to document best-practice information by default. If necessary, use TIP to highlight best-practice information that helps users use a product or complete a step or task more easily and efficiently. A TIP should provide useful advice or shortcuts that can enhance the user's experience.

  • CAUTION
    Use CAUTION to warn users about conditions or actions that can lead to undesirable outcomes, including personal injury or damage to equipment. CAUTION should be used to draw attention to potential hazards that the user must avoid to prevent harm or disruption.

Additional Guidelines

  • Only use supported admonitions. Any other kind of formatting is not supported.

  • Avoid overusing admonitions. Overuse can lead to users skipping over these important sections because they see them as the "junk drawer" of our docs.

  • As a rule of thumb, limit the number of admonitions to a maximum of 3 per page.

  • Provide clear and concise information within the admonition. The message should be brief and to the point, allowing users to quickly understand the importance of the information provided.

  • Avoid AsciiDoc admonitions in a table. If content needs to be identified as a note, tip, or caution, use Note:, Tip:, or Caution: as an inline lead-in to the text.

after (versus "once")

  • Use "after" to indicate a chronology: "Turn on your computer after you plug it in."

  • Use "once" only to mean "one time."

also

  • Use "also" to mean "additionally."

  • Don't use "also" to mean "alternatively."

and/or

Choose the more precise term if there is one. If neither term is more precise than the other, use "and/or."

as

Don't use "as" to mean "because."

by using (versus "using" or "with")

  • Use "by using" when the entity that is doing the using is the subject: "You can add new components to the repository by using the Components menu."

  • You can begin a sentence with either "using" or "with," which are sometimes acceptable with product names: "Using SnapDrive, you can manage virtual disks and Snapshot copies in a Windows environment."

can (versus "might," "may," "should," or "must")

  • Use "can" to indicate capability: "You can commit your changes at any time during this procedure."

  • Use "might" to indicate possibility: "Downloading multiple programs might affect processing time."

  • Don't use "may," which is ambiguous because it could mean either capability or permission.

  • Use "should" to indicate a recommended but optional action. Consider using an alternative phrase instead, such as "we recommend."

  • Avoid using "must" because it's passive. Consider restating the thought as an instruction using imperative voice. If you use "must," use it to indicate a required action or condition.

capitalization

Use sentence-style capitalization (lowercase) for almost everything. Only capitalize:

  • The first word of sentences and headings, including table headings

  • The first word of list items, including sentence fragments

  • Proper nouns

  • Doc titles and subtitles (capitalize all major words and prepositions of five or more letters)

  • UI elements, but only if they are capitalized in the interface. Otherwise, use lowercase.

caution notices

Refer to admonitions.

contractions

Use contractions as part of writing conversationally.

ensure (versus "confirm" or "verify")

  • Use "ensure" to mean "to make certain." Include "that," as appropriate: "Ensure that there is sufficient white space around illustrations."

  • Never use "ensure" to imply a promise or guarantee: "Use Cloud Manager to ensure that you can provision NFS and CIFS volumes on ONTAP clusters."

  • Use "confirm" or "verify" when you mean that the user should double-check something that already exists or has happened already: "Verify that NFS is set up on the cluster."

graphics

Refer to Use lots of visuals.

grammar

Except where noted otherwise, follow the grammar, punctuation, and spelling conventions detailed in:

if not

Don't use "if not" by itself to refer to the previous sentence:

  • Rather than this: "The computer should be off. If not, turn it off."

  • Do this: "Verify that the computer is off."

if (versus "whether" or "when")

  • Use "if" to indicate a condition, such as in "if this, then that" constructions.

  • Use "whether" when there is a stated or implied "or not" condition. To ease translation, it is often best to replace "whether or not" with "whether" alone.

  • Use "when" to indicate a passage of time.

imperative voice

Refer to Write actively.

future functionality or releases

Don't refer to the timing or content of upcoming product releases or features, other than to say that a feature or function is "not currently supported."

KB articles: referring to

Refer to KB (NetApp Knowledgebase) articles in content when appropriate. For resources pages and GitHub content, put the link in running text.

lists

Lists of info are usually easier to scan and absorb than blocks of text. Consider ways to simplify complex info by presenting it in list form. Here are some general guidelines, but use your judgment:

  • Make sure that the reason for the list is clear. Introduce the list with a complete sentence, a sentence fragment with a colon, or a heading.

  • When using a list inside a list, limit the structure to at most two levels of depth to maintain clarity and readability. If you find yourself needing more levels, consider reorganizing the content to make it easier for users to navigate and understand.

  • Any list, including nested lists, should have between two and seven entries. In general, the shorter the info in each entry, the more entries you can add while keeping the list scannable. If a list has multiple entries that contain nested lists, consider using sections or block titles to divide the entire thing into more consumable chunks.

  • List entries should be as scannable as possible. Avoid blocks of text that get in the way of keeping list entries scannable.

  • List entries should start with a capital letter, and list entries should be grammatically parallel. For example, start each entry with a noun or a verb:

    • If all list entries are complete sentences, end them with periods.

    • If all list entries are sentence fragments, don't end them with periods.

  • List entries should be ordered in a logical way, such as alphabetically or chronologically.

localization

Refer to Write for a global audience.

minimalism

Refer to Write minimally.

numbers

  • Use Arabic numerals for 10 and all numbers greater than 10, with these exceptions:

    • If you begin a sentence with a number, use a word, not an Arabic numeral.

    • Use words (not numerals) for approximate numbers.

  • Use words for numbers that are less than 10.

  • If a sentence contains a mixture of numbers less than 10 and greater than 10, use Arabic numerals for all numbers.

  • For additional number conventions, see Microsoft Writing Style Guide.

plagiarism

We document NetApp products and the interaction of NetApp products with third-party products. We do not document third-party products. We should never need to copy and paste third-party content into our docs and we should never do it.

prerequisites

Prerequisites identify the conditions that must exist or the actions that users must have completed before they start the current task.

  • Identify the nature of the content with a heading, such as "Prerequisites," "Before you begin," or "Before you get started."

  • Use passive voice for prerequisite wording if it makes sense to do so:

    • "NFS or CIFS must be set up on the cluster."

    • "You must have the cluster management IP address and the password for the admin user account to add the cluster to Cloud Manager."

  • Clarify the prerequisite as needed: "NFS or CIFS must be set up on the cluster. You can set up NFS and CIFS using System Manager or the CLI."

  • Consider other ways to present the information, for example whether it would be appropriate to reword the content as the first step in the current task:

    • Prerequisite: "You must have the required permissions before you deploy your first cluster."

    • Step: "Provide the required permissions to deploy your first cluster."

prior (versus "before," "previous," or "preceding")

  • If possible, replace "prior" with "before."

  • If you can't use "before," use "prior" as an adjective to refer to something that occurred earlier in time or with a higher order of importance.

  • Use "previous" to indicate something that occurred at an unspecified time earlier.

  • Use "preceding" to indicate something that occurred immediately beforehand.

punctuation

Keep it simple. In general, the more punctuation included in a sentence, the more brain cells it takes to understand.

  • Use a serial comma (Oxford comma) before the conjunction ("and" or "or") in a narrative list of three or more items.

  • Limit use of semicolons and colons.

  • Except where noted otherwise, follow the grammar, punctuation, and spelling conventions detailed in:

since

Use "since" to indicate a passage of time. Don't use "since" to mean "because."

spelling

Except where noted otherwise, follow the grammar, punctuation, and spelling conventions detailed in:

that (versus "which" or "who")

  • Use "that" (without a trailing comma) to introduce clauses that are required for the sentence to make sense.

  • Use "that" even if the sentence is clear in English without it: "Verify that the computer is off."

  • Use "which" (with a trailing comma) to introduce clauses that add supporting information but are not required for the sentence to make sense.

  • Use "who" to introduce clauses referring to people.

trademarks

We don't include trademark symbols in most of our technical content because the legal statements in our templates are sufficient. However, we do follow all usage rules when using NetApp trademarked terms:

  • Use trademarked terms (with or without the symbol) only as adjectives, never as nouns, verbs, or verbals.

  • Don't abbreviate, hyphenate, or italicize trademarked terms.

  • Don't pluralize trademarked terms. If a plural form is required, use the trademarked name as an adjective that modifies a plural noun.

  • Don't use a possessive form of a trademarked term. You can use the possessive form of company names, such as NetApp, when the names are being used in a general sense, rather than as trademarked terms.

user interface

When you are documenting a user interface, rely on the interface as much as possible to guide the user.

General guidelines

Use a simple and mimimal style when documenting UIs.

Details

  • Assume that the user is using the interface while reading the content:

    • Don't walk the user through a wizard or screen step by step. Only call out important things that are not apparent from the interface.

    • Don't include "click OK" or "click Save" or "the volume is created" or anything else that's obvious to someone doing the task.

    • Assume success. Unless you expect an operation to fail most of the time, do not document the failure path. Assume that the interface provides proper guidance.

  • Don't use "click" at all. Always use "select" because that word covers mouse, touch, keyboard, and any other way of making a choice.

  • Focus content on a workflow that addresses a customer use case and on getting the user to the right place in the interface to start the workflow.

  • Always document the one best way to achieve the user goal.

  • If the workflow requires a significant decision, make sure to document a decision rule.

  • Use the minimum number of steps necessary for most users most of the time.

Naming UI elements

Avoid documenting to the level of granularity that requires naming UI elements.

Details

Rely on the interface to guide the user through the specifics of the interaction. If you must get that specific, name the label on the element. For example, "Select the desired volume" or "Select 'Use existing volume'." There is no need to name menus or radio buttons or checkboxes, just use the label.

For icons that users must select, use an image of the icon. Don't try to name it. This rule applies to icons like the arrow, pencil, gear, kabob, hamburger, and so on.

Representing displayed labels

Follow the spelling and capitalization used by the user interface when identifying labels.

Details

If a label is followed by ellipses, do not include the ellipses when naming the object. Encourage developers to use title-style capitalization for user interface labels, to make writing about them easier.

Using screen captures

Use screen captures sparingly.

Details

An occasional screen capture ("screenshot") helps users be confident that they are in the right place in an interface when starting or changing interfaces during a workflow. Don't use screen captures to show what data to enter or what value to select.

while (versus "although")

  • Use "while" to indicate something occurring in time.

  • Use "although" to represent an activity that occurs at nearly the same time or shortly after another activity.