Where possible, prefer active voice over passive.
Incorrect | Correct |
---|---|
It can be put into the configuration mode by grounding the CONFIG pin on the transceiver. | - You can put it into the configuration mode by grounding the CONFIG pin on the transceiver. - To put it into the configuration mode, ground the CONFIG pin on the transceiver. - Put it into the configuration mode by grounding the CONFIG pin on the transceiver. |
- Capitalize the first word in the description of an entity.
Incorrect | Correct |
---|---|
checks to see if there is data available for reading | Checks to see if there is data available for reading |
@param len length of the buffer | @param len Length of the buffer |
- Be consistent with the capitalization of boolean values.
Incorrect | Correct |
---|---|
Returns True on success, false otherwise | - Returns true on success, false otherwise - Returns True on success, False otherwise |
Do not use possessive case to avoid unnecessary personalization.
Incorrect | Correct |
---|---|
method's output | - method output - output of the method |
Use the present simple tense instead of future, past, or present perfect.
Incorrect | Correct |
---|---|
When specified, this value will be used in computing the voltage. | When specified, this value is used in computing the voltage. |
Once the data has been read… | Once the data is read… |
Use second person when addressing the target reader of your comment.
Incorrect | Correct |
---|---|
The user can easily override this method. | You can easily override this method. |
Use third-person verb forms in short descriptions of classes, methods, functions, etc., not infinitive.
Incorrect | Correct |
---|---|
Get the proximity value from the sensor | Gets the proximity value from the sensor |
Add an extra comma before the last item in a list joined by and / or.
Incorrect | Correct |
---|---|
Returns raw values for the X, Y and Z axes. | Returns raw values for the X, Y, and Z axes. |
Do not put a period if the description of an entity is one sentence long.
Incorrect | Correct |
---|---|
Returns the name of the sensor. | Returns the name of the sensor |
Sets the frequency modulation Valid values are between 10 and 160 (in kHz) |
Sets the frequency modulation. Valid values are between 10 and 160 (in kHz). |
@param millis Maximum time in milliseconds to wait for the input -1 means waiting forever (default) |
@param millis Maximum time in milliseconds to wait for the input. -1 means waiting forever (default). |
Exception: if the description contains more than one sentence, put periods after each sentence.
- Spell out the first occurrence or the first prominent use of an abbreviation or acronym, followed by a shortened form.
Incorrect | Correct |
---|---|
@brief API for the GP2Y0A family of IR Proximity Sensors | @brief API for the GP2Y0A family of infrared (IR) Proximity Sensors |
- Do not use Latin abbreviations.
Incorrect | Correct |
---|---|
Works best with halved values; e.g., 1.0, 0.5, 0.25, etc. | Works best with halved values; for example, 1.0, 0.5, 0.25, and so on. |
- Know exactly what the abbreviation or acronym means to avoid unnecessary duplication.
Incorrect | Correct |
---|---|
- LCD display - ISR routine |
- LCD / liquid-crystal display - ISR / interrupt service routine |
Adjectives of the form number + noun / participle should be hyphenated. It does not matter if a number is represented by one or more digits or spelled out.
Incorrect | Correct |
---|---|
- 4 wire stepper motor - 3 axis gyroscope - zero based indexing - one byte register |
- 4-wire stepper motor - 3-axis gyroscope - zero-based indexing - one-byte register |
Use app when referring to a program running on a device, and application when referring to a program running on a desktop / laptop computer.
Incorrect | Correct |
---|---|
The wiki page for this device includes a link to an Android* application that can be used to read the device via NFC. | The wiki page for this device includes a link to an Android* app that can be used to read the device via NFC. |
If a function is associated with a class, use method instead.
Incorrect | Correct |
---|---|
class WheelEncoder { ... /** * Starts the counter. This function also clears * the current count and resets the clock. */ void startCounter(); |
class WheelEncoder { ... /** * Starts the counter. This method also clears * the current count and resets the clock. */ void startCounter(); |
Use onboard.
Incorrect | Correct |
---|---|
This ADC features an on-board reference and oscillator. | This ADC features an onboard reference and oscillator. |
Use a sensor name alone or a sensor model followed by a sensor name, not a sensor model alone.
Incorrect | Correct |
---|---|
ADXL345 is compatible with… | - The ADXL345 3-axis digital accelerometer is compatible with… - The accelerometer is compatible with… |
Exception: you can use a sensor model alone when introducing a sensor for the first time:
ADXL345 is a 3-axis digital accelerometer…
Setup is a noun, set up is a verb.
Incorrect | Correct |
---|---|
It does not require any additional set up. | It does not require any additional setup. |
For instructions on how to setup…, refer to... | For instructions on how to set up…, refer to... |
Use Wi-Fi.
Incorrect | Correct |
---|---|
It was tested with the XBee* S6B WiFi module. | It is tested with the XBee* S6B Wi-Fi* module. |
Use the correct official names of Intel products. When in doubt, check the TM names database.
Incorrect | Correct |
---|---|
It is a 64x48 pixel OLED display that connects directly to an edison via its 80-pin connector. | It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison board via its 80-pin connector. |
Note: if an Intel product has a legally approved short name, you may use it in subsequent instances, after spelling it out the first time.
Add an asterisk (*) after a name to indicate a third-party trademark or registered intellectual property. If you are not sure whether an asterisk is necessary after a particular name, the rule of thumb is to put one, to be on the safe side.
Incorrect | Correct |
---|---|
The Grove MQ2 Gas Sensor module is useful for gas leakage detection. | The Grove* MQ2 Gas Sensor module is useful for gas leakage detection. |
Always follow trademarks by an appropriate noun. For a list of approved nouns for a particular trademark, check the TM names database.
Incorrect | Correct |
---|---|
It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison via its 80-pin connector. | It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison board via its 80-pin connector. |
For titles, use sentence capitalization.
Incorrect | Correct |
---|---|
Add a New Device | Add a new device |
For GUI elements and file names, use bolding instead of quotes.
Incorrect | Correct |
---|---|
In the “Environment Variables” window, click “OK”. | In the Environment Variables window, click OK. |
Copy the “example.zip” archive into the installation directory. | Copy the example.zip archive into the installation directory. |
Enclose program commands, code blocks, and file paths in backticks (`).
Incorrect | Correct |
---|---|
To create a new device, use the create-thing command. | To create a new device, use the `create-thing` (rendered as create-thing ) command. |
Go to C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws. | Go to `C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws` (rendered as C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws ). |
Do not use embedded links to third-party websites.
Incorrect | Correct |
---|---|
Create an account on Microsoft Azure, if you do not yet have one. | Create an account on https://azure.microsoft.com/en-us, if you do not yet have one. |
- For a logical sequence of steps, use a numbered list.
Incorrect | Correct |
---|---|
When running your C++ code on the Edison, you need to set the MQTT parameters in Eclipse. Go to "Run configurations", and change the "Commands to execute before application" to the following: … Click on the "Apply" button to save these settings. Click on the "Run" button to run the code on the Edison. |
When running your C++ code on the Intel® Edison board, you need to set the MQTT* client parameters in Eclipse*. To do that: 1. Go to Run configurations and, in the Commands to execute before application field, type the following: … 2. Click the Apply button to save these settings. 3. Click the Run button to run the code on your board. |
- For a list of equally important options, use a bulleted list.
Incorrect | Correct |
---|---|
From this exercise, developers will learn how to: 1. Connect the Intel® Edison board... 2. Run these code samples in the Intel® System Studio IoT Edition... 3. Set up a web application server... |
From this exercise, developers will learn how to: - Connect the Intel® Edison board… - Run these code samples in the Intel® System Studio IoT Edition… - Set up a web application server… |
Login is a noun, log in is a verb.
Incorrect | Correct |
---|---|
Provide your log in and password. | Provide your login and password. |
Login to your account. | Log in( )to your account. |
Omit on after click.
Incorrect | Correct |
---|---|
Click on Advanced system settings. | Click Advanced system settings. |
Do not use SSH as a verb. It is considered slang and is to be avoided.
Incorrect | Correct |
---|---|
SSH into your Intel® Edison board. | Establish an SSH connection to your Intel® Edison board. |