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

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.