Writing Tips – Technical Writing by Brian Lange

Address the reader as “You” and use the phrase “You can” frequently. This is better than using a neutral writing style. For example, the sentence “It is possible to view cpu usage by viewing the dashboard.” should be “You can view cpu usage by viewing the dashboard.”
Use singular nouns rather than plural ones. It makes the writing simpler, more accurate and easier for the writer to maintain. For example, the phrase “EBS volumes are created in a specific Availability Zone” is better written as “An EBS volume is created in a specific Availability Zone.”
The present tense should almost always be used. For example, the passage “Your users can easily navigate to this URL and see the image. But they probably don’t know that their request was routed from one network to another—through the complex collection of interconnected networks that comprise the internet—until the image was found” should be changed to “Your users can easily navigate to this URL and see the image. But they probably don’t know that their request is routed from one network to another—through the complex collection of interconnected networks that comprise the internet—until the image is found.’
There is often a better and stronger alternative to the word “might.” The phrase “You might be working with data that requires frequent audits to ensure compliance with internal policies and best practices” should be written “You can efficiently work with data that requires audits, helping you ensure compliance with internal policies, and follow best practices. In this sentence the word “might” can be removed “You can use AWS Health events to learn how service and resource changes might affect your applications running on AWS.”
Better: “You can use AWS Health events to learn how service and resource changes affect your applications running on AWS.”
The word “to [verb]” frequently has a good alternative. In the first example sentence in #4 above, “to ensure” is changed to just “ensure”
Use the word “See” when instructing the reader to click on a link in order to read an article. An alternative is to use the word “Read” but “See” is slightly better and a little warmer.
Words such as “typically” and phrases like “In some cases” involve probability. When you use words that involve probability such as “likely” or “frequently,” make sure the words in the rest of the sentence are appropriate. For example, the sentence “Typically users can have one of the following roles” is incorrect because users can “always” have one of those roles. The correct word to use is “will,” the sentence should be written as “Typically users will have one of the following roles.” Similarly, the sentence “In some cases, you might have underlying resources that you want to upgrade incrementally, should be written as “In some cases, you will have underlying resources that you want to upgrade incrementally.”
Eliminate use of “that” and “that are.” For example, the sentence “Amazon EC2 provides a wide selection of instance types optimized for different use cases” is a little better than: “Amazon EC2 provides a wide selection of instance types that are optimized for different use cases” .
Use the word “choose” when directing a user to click a link, select an item from a drop down menu, or select a checkbox. “Choose” is a better alternative to “click.”
The word “will” is often unnecessary. For example, the sentence “To access reports in the platform, you will need to have the right permissions:” can be written as “To access reports in ABC Co, you need to have the right permissions:”
Do not use the word “enable” when your sentence describes granting users functionality. It is better to use words like “let,” “offer” or “allow” or phrases like “provide the ability to.” “Enable” is more appropriate for a group of people. For example, the sentence “The software enables your marketing team to be more productive” is appropriate. However, “The software allows you to be more productive” is better when talking about an individual person.
Don’t use the word “via.” Use “by” or something similar to keep the writing simple.
The sentence “You can also optionally select” is better written as “You also have the option of selecting.” Similarly, the phrase “you can additionally create” is better as “Additionally, you can create.” Moreover, the sentence “You can also configure CloudFront to return a custom error page when a request is blocked.” should be written as “You can configure CloudFront to return a custom error page when a request is blocked.”
If there are a more than a few words inside of parentheses, consider making it a complete sentence or a sentence fragment. For example, the following could be transformed into a sentence fragment “(in order to avoid a possible accidental deletion due to a malformed TTL value).”
Don’t use the abbreviations i.e., or e.g. Instead use the full word phrase such as “For example.”
“Following” is a three syllable word and is often used before a list of things is described. An alternative is to use the word “here” as in “Here is a list of properties…” If you use the word following as in “The following is a list of properties” you should always use “following.”
“Go to” should be used in instructions when indicating that a url should be accessed by a user. This is better than using “visit” or “access.”
“Open” is also a good possibility when instructing a user to view a url.
Marketing words like “easily” and “simply” should be used sparingly. They often don’t add value for the reader. For example, the phrase “you can easily click on the link to view website metrics” should be “you can click on the link to view website metrics.” Additionally, marketing words like “simplifies” are better when used to describe a service. For example, “Azure Cosmos DB simplifies these challenges” is effective. Similarly, the sentence “By using CloudFormation, you easily manage a collection of resources as a single unit.” should be written as “By using CloudFormation, you can manage a collection of resources as a single unit.” The “easy” is implicit and known to the knowledgeable reader.
Avoid jokes. There shouldn’t be any humor. Jokes in technical writing get old the second they hit the paper.
The word “will” can frequently be removed from a sentence. For example, the sentence “This article will enumerate some of the key benefits of NoSQL databases” is better written as “This article enumerates some of the key benefits of NoSQL databases.”
“When” can be better than “if” when a scenario is likely to happen or if the possible scenario is advantageous. For example, the phrase “If your transactional volumes are reaching extreme levels” is better written as “When your transactional volumes reach extreme levels.”
Only provide an order list of items when the order does in fact matter. If the order doesn’t matter, use an unordered list. For example, the points made after the phrase “the software offers the following functionality” should be an unordered list.
The word “largely” is not an effective word. For example, the phrase “The type of CMK that you create depends largely on how you plan to use the CMK” is better written as “The type of CML that you create mostly depends on how you plan to use the CMK.”
Avoid using “or” when “and” is more appropriate. For example, the phrase “Because Amazon RDS takes over many of the difficult or tedious management tasks” is better written as “Because Amazon RDS takes over many of the difficult and tedious management tasks.”
Make sure “Greater” is used instead of “Larger” when the value is numeric. For example the sentence “We recommend that you specify a period in your request that is equal to or larger than the collection period to ensure that the returned data is valid” is better written as “We recommend that you specify a period in your request that is equal to or greater than the collection period to ensure that the returned data is valid.”
There is often a better alternative than using the word “of”. For example the phrase “Amazon EC2 restricts traffic on port 25 of all instances by default” is better written as “On all instances, Amazon EC2 restricts traffic on port 25 by default.”
The title of an article can frequently begin with the word “What” For example, an article on AWS s3 Outputs is titled “What is AWS Outposts”? Using the word “What” makes the article more engaging by using a phrase that is similar to something the reader would ask.
When you link to an article within your existing article, the link should open up a new tab in the browser.
Be careful with the word automatically. For instance, when I plug in my fridge it doesn’t keep the fool cold automatically. For example, “automatically” in the following sentence is somewhat unnecessary: “After you enable TTL on a table, a per-partition scanner background process automatically and continuously evaluates the expiry status of items in the table.” The automatic nature of the process can be implicit.
When describing an application use the phrase “is built” instead of “was built. This tip is inline with using the present tense the vast majority of the time.
Try not to use double “ofs” For example, the sentence: “The following are some of the advantages of using Amazon S3” can better be written as “The following are some advantages of using using Amazon S3”.
I prefer “for more information on” than “for more information about”. Regardless, you should stick to one or the other. “information on” has the connotation of being about a specific subject rather a broad topic. For example, “for more information on security groups see…”, while “for more information about computer programming see…”
The word “or” is frequently used when “and” is more appropriate. For example, in the sentence “You create a template that describes all the AWS resources that you want (like Amazon EC2 instances or Amazon RDS DB instances)” should be written as “You create a template that describes all the AWS resources that you want (like Amazon EC2 instances and Amazon RDS DB instances) “
Use the word “effective” in place of “easily”. For example, the sentence “To more easily debug multi-point failures, we recommend that you collect monitoring data from all parts of your AWS solution.” should be written as “To more effectively debug multi-point failures, we recommend that you collect monitoring data from all parts of your AWS solution.”
Don’t welcome the reader to the user guide. For example, “Welcome to the Amazon DynamoDB Developer Guide.” Honestly, this is somewhat okay but if you use this phrase, you should use it on every document and it is just easier to eliminate it.
A user should “complete” steps rather than “follow” steps. For example, “Follow these steps to enable Time to Live using the DynamoDB console:” should be changed to “Complete these steps to enable Time to Live using the DynamoDB console:”
When you first use a proprietary label, that is something that has a unique and proper name in your application, the word should be italicized. In subsequent usage, the term should not be italicized. For example, “You can use AWS Health events to learn how service and resource changes might affect your applications running on AWS.”
Long dashes should following a topic in a bulleted list. For example, https://docs.aws.amazon.com/health/latest/ug/first-time-user.html
You “sign in the application” and not “sign into the application.
Don’t be afraid of slightly choppy writing. Being succinct and direct is often more important than a flowing style of writing.
username should be one word rather than two.
If you use the word “this” make sure there is a “this” and make sure it is not a “that”. For example, this sentence correctly uses “that”: “When activity occurs in your AWS account, that activity is recorded in a CloudTrail event.” It is a common mistake to use the word “this”
Use “email” instead of “e-mail”
It is better to use the word “last” rather than “past”. For example, the sentence “Event history allows you to view, search, and download the past 90 days of activity in your AWS account.” is better written as “Event history allows you to view, search, and download the last 90 days of activity in your AWS account.”
Don’t use the word “page” to refer to the current document. The sentence “This page contains step-by-step instructions on how to get started with Docker. In this tutorial, you’ll learn how to:” should use the word “document”, “article”, “tutorial”, or “guide”.
Words like “Simply” are often unnecessary. For example, the sentence “A Dockerfile is simply a text-based script of instructions that is used to create a container image.” is better written without the word “simply” “A Dockerfile is a text-based script of instructions that is used to create a container image. The idea is to tell the reader what something is and they can decide the relative complexity of it.