Write clear and concise sentences and paragraphs#
Users can understand wordy and complex writing, and they can wade through walls of text, but we shouldn't force them to. Use the following guidelines to help you write clear and concise sentences and paragraphs.
- Use a consistent sentence structure
- Restrict sentence length
- Use only, but all of, the necessary words
- Create short paragraphs
Use a consistent sentence structure#
As often as possible, use the sentence structure subject—verb—object. Use simple declarative sentences for descriptions, and use simple imperative sentences for instructions. However, you can use a sentence structure that starts with an if clause or places the condition before the action.
|The value is truncated only when it's stored in an integer value.||Only when stored in an integer variable is the value truncated.|
|To bake a cake, follow these steps.||Take a look at the following procedure below to bake a simple cake.|
|If you must monitor clients from the host, you can configure your settings in the directory.||You can configure your settings in the directory if you must monitor clients from the host.|
Restrict sentence length#
Even a well-written long sentence can be hard to follow and understand. Try to limit sentences to 20-25 words. If you must write a longer sentence, it should have more than one clause, and the relationship between the clauses should be clear.
|After you choose a data center, the app retrieves a list of the containers that are hosted within that data center. The number of files in each container and the approximate size of each container are displayed.||After you choose a data center, the app retrieves a list of the containers that are hosted within that data center, along with the number of files in each container and the approximate size.|
|Select whether to overwrite files with the same name or to restore files to their original folders. Then, click Next.||Click the check boxes to confirm whether you would like to Overwrite files with the same name or restore the files to their original folders and then click the Next button.|
Use only, but all of, the necessary words#
Technical writing isn't creative writing. Use only the words necessary to convey the meaning, and strip out anything extraneous. For example, are you using adverbs (modifiers ending in -ly)? If so, you can remove most of them without changing the meaning. What about adjectives? If they aren't necessary to the meaning, remove them. Can prepositional phrases be shortened? Are you using empty phrases that don't clarify the content?
Conversely, be sure to include all the words that are necessary to make the meaning of a sentence clear. Include all necessary articles (a, an, the), prepositions, connectors, and other syntactic cues, such as those described in Clarify gerunds and participles, Use that and which correctly, and Use pronouns carefully.
|You can use the product to generate temporary URLs for files and share the files with other people.||A great feature implemented by the product is the ability to generate temporary URLs for files and share them with other people.|
|Use the Control Panel to create servers easily and quickly.||The well-designed Control Panel is your passport to creating servers in an easy, fun way right away.|
|SharePoint is the logical choice for business collaboration, content management, and business intelligence.||The flexibility, extensibility, rich feature set and ease-of-use offered by SharePoint make it the logical choice for many businesses when it comes to their Collaboration, Content Management and Business Intelligence needs.|
|In an environment where the product is running, you can use the ESP utility to monitor and audit your backup and recovery activities across the enterprise.||In an environment where the product is installed and running on one or more hosts, the ESP utility enables you to monitor your backup and recovery activities and audit your backup and recovery practices from an enterprise-wide perspective.|
|Empty the file.||Empty file.|
|The Label option isn't supported for this file format.||Label option not supported for file format.|
Create short paragraphs#
Short paragraphs are easier to scan and understand than longer ones. Use the following guidelines for paragraphs:
- Cover only one idea in each paragraph.
- Limit paragraphs to four to five sentences. However, avoid having one-sentence paragraphs.
- Use connective or transitional words to ensure flow within and between paragraphs.
- When listing three or more items, use a bullet list instead of embedding the items in a paragraph.
The following examples show how breaking up a long paragraph by using a list makes it easy for the user to scan the text.
From the Job Scheduler window, you can perform the following actions:
|From the Job Scheduler page, you can run a generated script immediately, schedule a generated script to run at a later time, track the execution of submitted jobs, and manage jobs in the job queue.|
Within the Cloud Storage App for Microsoft SharePoint, you can delete a single file or multiple files from a container:
When you delete a file, it's permanently removed from the Cloud Files container.
|Within the Cloud Storage App for Microsoft SharePoint, you can delete a single file or multiple files from a container. You can delete a single file by clicking the delete icon to the right of the file's name. You can delete multiple files at one time by selecting the cloud icon to the left of each file's name and then clicking Delete Selected. Rows that you select for deletion are highlighted with a dark gray background. When you delete a file, it's permanently removed from the Cloud Files container.|
For style guidelines for lists, see Lists.