<font color="red">Incorrect</font>	<font color="green">Correct</font>
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.

Capitalization

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

Parameters

len	length of the buffer

Parameters

len	Length of the buffer

Be consistent with the capitalization of boolean values.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
Returns True on success, false otherwise	- Returns true on success, false otherwise - Returns True on success, False otherwise

No possessive case

Do not use possessive case to avoid unnecessary personalization.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
method's output	- method output - output of the method

Present tense

Use the present simple tense instead of future, past, or present perfect.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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…

Second person vs the user / reader / programmer / engineer

Use second person when addressing the target reader of your comment.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
The user can easily override this method.	You can easily override this method.

Third person vs infinitive

Use third-person verb forms in short descriptions of classes, methods, functions, etc., not infinitive.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
Get the proximity value from the sensor	Gets the proximity value from the sensor

Punctuation

Comma in enumerations

Add an extra comma before the last item in a list joined by and / or.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
Returns raw values for the X, Y and Z axes.	Returns raw values for the X, Y, and Z axes.

No period at the end of description

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).

Parameters

millis Maximum time in milliseconds to wait for the input
-1 means waiting forever (default)

Parameters

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.

Specific word usage

Abbreviations and acronyms

Spell out the first occurrence or the first prominent use of an abbreviation or acronym, followed by a shortened form.

Do not use Latin abbreviations.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
- LCD display - ISR routine	- LCD / liquid-crystal display - ISR / interrupt service routine

Adjectives containing numbers

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.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
- 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

App vs application

Use app when referring to a program running on a device, and application when referring to a program running on a desktop / laptop computer.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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.

Function vs method

If a function is associated with a class, use method instead.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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();

Onboard vs on-board

Use onboard.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
This ADC features an on-board reference and oscillator.	This ADC features an onboard reference and oscillator.

Sensor name vs sensor model

Use a sensor name alone or a sensor model followed by a sensor name, not a sensor model alone.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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 vs set up

Setup is a noun, set up is a verb.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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...

Wi-Fi vs WiFi / Wifi / Wi-fi / wifi / wi-fi

Use Wi-Fi.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
It was tested with the XBee* S6B WiFi module.	It is tested with the XBee* S6B Wi-Fi* module.

Trademarks

Intel products

Use the correct official names of Intel products. When in doubt, check the TM names database.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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.

Third-party technology

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.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
The Grove MQ2 Gas Sensor module is useful for gas leakage detection.	The Grove* MQ2 Gas Sensor module is useful for gas leakage detection.

Trademark + noun

Always follow trademarks by an appropriate noun. For a list of approved nouns for a particular trademark, check the TM names database.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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.

Documentation Authoring Guidelines

Grammar

Capitalization

For titles, use sentence capitalization.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
Add a New Device	Add a new device

Styling

Bolding

For GUI elements and file names, use bolding instead of quotes.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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.

Backticks

Enclose program commands, code blocks, and file paths in backticks (`).

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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:-iot-examples-mqtt.	Go to `C:-iot-examples-mqtt` (rendered as `C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws`).

Links

Do not use embedded links to third-party websites.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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.

Numbered list vs bullet points

For a logical sequence of steps, use a numbered list.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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…

Specific word usage

Login vs log in

Login is a noun, log in is a verb.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
Provide your log in and password.	Provide your login and password.
Login to your account.	Log in( )to your account.

Click

Omit on after click.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
Click on Advanced system settings.	Click Advanced system settings.

SSH

Do not use SSH as a verb. It is considered slang and is to be avoided.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
SSH into your Intel® Edison board.	Establish an SSH connection to your Intel® Edison board.

<font color="red">Incorrect</font>	<font color="green">Correct</font>
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:-iot-examples-mqtt.	Go to `C:-iot-examples-mqtt` (rendered as `C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws`).