Style Guide
This article outlines the set of rules for writing and presenting text in the GrowerIQ knowledge base.
As Intercom updates the article editor, our formatting rules change to keep up. When editing an article, update any
outdated formatting.
In this article:
- Punctuation and Word Usage
- Capitalization
- Labeled Lists
- Formatting
- Notes, Cautions, and Warnings
- Article Structure
- Images/Screenshots
- General Writing Style
Punctuation and Word Usage
- Colons:
- Use in main body text to introduce a list.
- Use in headings in regular knowledge base articles to separate a description and what it pertains to.
- Example: QA: Samples
- Within a labeled list, use a colon followed by a space to separate the label from the explanatory text. The
label is bolded but the colon is not.
- Label: Explanatory text.
- Commas: When a sentence includes multiple items or concepts, include a comma immediately before a conjunction (the
serial or Oxford comma).
- Example: Your workforce uses desktops, laptops, and mobile devices.
- Contractions: Use contractions to make your writing sound friendly, but don't avoid overuse. If you notice your
content sounds unprofessional or lacks credibility with contractions, try removing them.
- Dashes:
- Avoid using an en dash (“–”) to connect an inclusive range of values. Use “to” instead.
- Avoid using an em dash (“—“) if possible. If used, it sets off a phrase that interrupts or changes the direction
of a sentence or sets off a lengthy list that would otherwise make the sentence confusing to read. Use a pair of
em dashes to surround the set-off text if it appears in the middle of the sentence.
- e.g.:Avoid. Use “for example” or “for instance” instead.
- etc.: Use at the end of a list to indicate that there are other items or examples that could be included, but are
not specifically mentioned because they are either obvious or not essential to the context.
- Hyphen: Use to divide words and to combine compound words and numbers, such as phone and Social Security numbers.
- Location compounds: Hyphenate compounds such as a lower-left corner, top-right portion.
- Units of measure: Hyphenate a unit of measure in a compound adjective: 3.5-inch floppy disk, 4-GB hard disk.
- i.e.: Use within parentheses to introduce a rephrasing or clarification of the text preceding it.
- Example: (i.e., this is an alternate description).
- Numbers: Always use digits unless it would cause confusion.
- Only: Place the word "only" before the main verb of a sentence. It is easier to read.
- Good: You can only select batches in the vegetative phase.
- Bad: You can select only batches in the vegetative phase.
- Quotation marks: Follow these guidelines:
- Literal strings: Contrary to regular quoting, place punctuation marks outside the quotation marks unless they
are a part of the literal string.
- Example: Enter “1” into the field. If the field turns red, enter “2”. You can also enter “3”, “4”, or “5”.
Incomplete decimal numbers will not be accepted, such as "6.".
- Symbols: In general, use symbols when referring to a UI element containing them. For other usage, follow these
guidelines:
- @: Avoid. Use “at” instead.
- #: Avoid.
- $: Use to indicate a dollar amount. “$4.00” is preferred over “4 dollars”.
- %: Use to indicate a percentage amount. “10%” is preferred over “10 percent”.
- &: Avoid.
- *: Use after the end-punctuation of a sentence to indicate a possible exception. *
- * Do not use in headings.
- That vs. which: use “that” for essential clauses important to the meaning of a sentence, and without commas. Use of
“which” denotes a nonrestrictive (nonessential) clause, which must be set off by a comma.
- Correct: It is a threat that is hard to analyze because of its multiple components.
- Correct: It is a multi-component threat, which makes it hard to analyze.
- Incorrect: It is a multi-component threat, that makes it hard to analyze.
- Incorrect: It is a threat which is hard to analyze because of its multiple components.
Capitalization
- Glossary terms: Capitalize in the same way they appear in the glossary.
- Headings and Labels: Use title case for first-level headings (H1) and second-level headings (H2). Use the Title
Capitalization Tool (APA style) when in doubt. Use sentence case for third-level headings (H3) and beyond.
- Labeled lists: Capitalize the first word of each label and the first word of the explanatory text, even if it is
not a complete sentence. See below for a full explanation of labeled lists.
- General lists: Capitalize the first word of each item, unless the item as a whole refers to a UI element whose
first word is not capitalized.
- UI elements: Capitalize text referring to UI elements in GrowerIQ as follows:
- If the UI element comprises more than one word, use title case, even if the UI element itself doesn't.
- Example: The Add Item button appears when the order is approved.
- If the UI element is one word, follow its capitalization.
- Example: Click SUBMIT to complete the action.
Labeled Lists
Use a labeled list when you are listing items that need further explanation. These can be bulleted or numbered. The
bulleted lists in the previous sections are good examples. Start the list item with the item to be explained (the
“label”) and follow it with a colon. After the colon, write the explanation.
Capitalize the first word of each label and the first word of the explanatory text, even if it is not a complete
sentence. Bold the label.
The explanatory text can be either an imperative sentence to explain what to do with the item, or a phrase that
describes the item.
Here is an example.
- Type: Select whether the lot is packaged or unpackaged. The lot can only be assigned to SKUs whose "packaging type"
matches your selection.
- Room: The room the lot item is currently in. This cannot be changed.
Tables
Use a grey background for the header row and bold the header text.
Cell shading is a relatively new feature. Update old, non-shaded header rows when necessary.
The table below is a good example.
Formatting
| | | | --- | --- | | Rule | Example | | Bold text that describes a UI element that the user interacts with. | Open the
App Drawer and click Facility Settings. Click the Prescriptions tab. From the Partner Group drop-down menu, select a
partner group. | | Use a colon to separate term/definition or term/explanation pairs. | ID: Sorts by the discount code
ID numbers. Code: Sorts by the codes used to claim the discounts. | | Place notes, cautions, and warnings inside
callouts. Blue for notes, yellow for cautions, red for warnings. | (See the section below for examples) | | Bold
cautions and warnings, and use ALL-CAPS for warnings. | This is a caution. THIS IS A WARNING. | | If the note, caution,
or warning is within a table, callouts are unavailable. Bold the word "note", "caution", or "warning", and italicize the
text. | Note*: This is a note within a table cell.* | | Bold labels in a labeled list, excluding the colon. | - Label:
Explanatory text. |
Notes, Cautions, and Warnings
Use these to grab the reader's attention and let them know about something important or useful.
Notes
Use notes when the reader should stop to consider whether this is the right action to take or to consider minor
consequences of an action that can be undone relatively easily.
Here's an example:
You can't change the SKU's unit once it's been set up.
Cautions
Use cautions when the reader needs to know about an irreversible consequence.
Bold cautions.
Here's an example.
If you mark this SKU as "archived" during creation, it can never be used.
Warnings
Use warnings when an action will cause irreversible consequences that will likely cause data loss or a major disruption.
Here's an example.
IF YOU DELETE THIS ENTITY, ALL BATCHES ASSOCIATED WITH IT WILL BE DELETED AS WELL. THIS CANNOT BE UNDONE.
Article Structure
This section describes how to put article sections together and what to include in them.
Article Introduction
Introduce an article by answering the following questions, as applicable:
- What is the thing you’re talking about? Give a definition. (Almost always necessary)
- What can you do on this page? Use the page to… (Only include this if the entire article is about a single GrowerIQ
page that allow the user to do multiple different things and each thing is covered in separate sections of the
article)
- Why does GrowerIQ require you to do this? (Sometimes necessary)
- How does it affect the system or what does it unlock? Explain how it changes the way things appear, the way
workflows are done, or what it allows you to do in other areas of the system once you complete the outlined steps.
(Usually necessary)
- What are the recommended ways of setting it up? State any recommendations or link to an article of best practices.
(Sometimes necessary)
- Is there a general workflow you need to follow? If the article is specific to one entity, such as describing how to
work with a batch, a lot, etc., link to any relevant workflow articles. For example, the article about batches links
to the article about working through a batch plan. (Sometimes necessary)
- What are the prerequisites? Add a Prerequisites section with a bulleted list of prerequisites, if any. (Sometimes
necessary)
Content Order
Order the content in articles according to the hierarchy listed below. Of course, exclude any parts that don't apply to
the article you're working on.
For standard articles:
1. Introduction
2. "In this article" list
- Required if the article has multiple sections or procedures. The bulleted list items are links to each important
section heading.
3. Procedures
1. Procedure on adding/creating
- Use the heading "Adding a ..." if the entity being added doesn't normally get modified over time. For
example, a Room generally doesn't change, so "Adding a Room" is the correct heading.
- Use the heading "Creating a..." in all other cases. For example, a batch is continuously changing, so
"creating a batch" is the correct heading.
2. Procedure on viewing/editing
- Use the heading "Viewing a ..." for procedures that show how to view but not modify something.
- Use the heading "Editing a ..." for procedures that show how to edit the properties of something.
4. Description of relevant controls, such as buttons and fields. This entire part can sometimes be part of a procedure
outlined above if using the controls is all part of one procedure.
Use this article as an example.
For workflow articles:
Articles that describe an overarching workflow with many stages are structured differently.
1. Introduction
2. "In this article" list
3. Important concepts and/or procedures that apply to the main topic
4. Stages of the workflow, with each containing relevant explanations, conditions, controls, and procedures.
Use this article as an example.
Images/Screenshots
Only add a screenshot in one of these cases:
- When what you're describing would require more than a few words ANDthe screenshot would contain little to no text.
- If you're explaining an icon button.
- Note*: A screenshot of a button should only include the icon, not the button text. This prevents us from having
to take manage multiple versions of the screenshot for each translation of the article.*
General Writing Style
- Write in the imperative mood if the user has to follow your instruction to do something correctly. Avoid "you", “you
can”, or "let's".
- Bad: You can enter the batch number in the field.
- Good: Enter the batch number in the field.
- Use the active voice whenever possible.
- Bad: The list of discount codes can be sorted using these fields.
- Good: You can sort the list of discount codes using these fields.
- Use they/them as singular pronouns, rather than "he or she".
- Example: Prompt the client to enter their name in the field provided.
- Don't state a UI element’s type (button, window, etc.) unless it is a tab, field, or checkbox.
- Bad: Click the Save and Print Labels button.
- Good: Click Save and Print Labels.
- Good: On the New Info tab, under Driver Information, enter the driver’s full name in the Name field and select
the Active checkbox.
- Write “select the checkbox” when you want to direct the reader to place a checkmark in the checkbox. Write “clear
the checkbox” to direct the user to remove a checkmark from the checkbox.
- Example: Select the Include Discounts checkbox and clear the Include Wholesale Transactions checkbox.