Article Standards

When writing and reviewing your articles please stick to the following standards:

⚠	BE AWARE: This guidance has not always been followed in the past. Our standards have evolved over time. You may find older examples in the wiki that do not follow this advice.

General

Always use proper spelling and grammar.

Always ensure the accuracy of your statements. Verify your statements are accurate in Grooper before cementing them in an article. If you are having trouble, there are a number of resources in the company to help you.

• Get help from your documentation and training peers.
• Ask the Client Fulfillment team for help.
  • Help Desk sees problems from clients every day ranging from mundane, to bugs, to outright bizarre.
  • Professional Services members build solutions for clients and likely have some experience with what you're unfamiliar with.
  • Email: fulfillmenttech@bisok.com
• QA can help determine if something is a bug.
  • Email: qateam@bisok.com
• If all else fails, ask a dev. They are next door.

Double spacing after periods at the end of sentences is a digital to print standard. For content that lives purely in a digital environment, like Wiki articles, single spaces after periods is the accepted standard.

Bolding and italics

Bold all Grooper objects and services.

• What's an object? A good rule of thumb is anything you can add to the Node Tree is an object.
  • Batch
  • Batch Folder
  • Value Reader
  • Content Model
  • Data Model
  • Document Type
  • and so on
• What's a service? Grooper services installed from Grooper Config or Grooper Command Console.
  • Activity Processing
  • API Services
  • Import Watcher
  • and so on

Bold and Italicize all Grooper properties

• What's a property? Anything in a property configuration grid.
• Ex: A Value Reader only has one configurable property, the Extractor property.

Italicize all Grooper property settings in "How To" sections.

• Ex: On the Data Field, set the Display Width to 200

When referring to a property that has sub-property configurations, keep that property in bold italics.

• For example, Pattern Match is an Extractor Type.
  • It is not a Grooper object. So, it should not be bolded.
  • But it is more than just a simple property configuration. It is a set of properties.
    • "Pattern Match" makes it more visually apparent that it is a set of properties.
    • "Pattern Match" gives the impression that it is something simple like a true/false value or a simple dropdown choice that requires no further configuration.
• Other examples include:
  • All Activities (Recognize etc)
  • All Extractor Types (Labeled Value etc)
  • All Collation Providers (Ordered Array etc)
  • All Data Table Extract Methods (Tabular Layout etc)
  • All Behaviors (Labeling Behavior etc)
• BE AWARE: There is an exception to this rule.
  • When stating a setting configuration in a how-to instruction, always use simple italics.
  • Ex: Set the Value Extractor to Pattern Match.
    • However, after this point, whenever talking about Pattern Match more generally, you would use bold italics.

Tabs in the Grooper UI should be enclosed in "quotes".

• Ex: A Content Model's "Labels" tab.

Links

General link formatting

Always link to internal Grooper Wiki articles using the [[Article Name]] syntax. Ex:

• Tabular Layout
• [[Tabular Layout]]

For external links either:

• Use the full text syntax (aka "bare link")
  • https://www.grooper.com
  • https://www.grooper.com
• Or, use the nickname syntax (aka "nickname link")
  • Grooper
  • [https://www.grooper.com Grooper]
• NEVER use the footnote syntax (aka "annotation link")
  • [1]
  • [https://www.grooper.com]

"First mention" linking and icons

If a linkable topic exists multiple times in an article, link the word or phrase the first time it appears in an article's section.

• Linking to an article more than once per section crowds the topic and makes it more difficult to read.
• Beyond linking to a topic the first time is up to the author's discretion. If it makes sense to link to it more than the first time, you may do so.
• Ex: This is the first time we've mentioned Row Match. So, we linked to it. But if we mention Row Match afterwards, we don't need to link to it.

When a Grooper object is mentioned the first time in an article, you should also prepend the link with that object's icon.

• Icons can be inserted inline with text as an image.
• This image files are already uploaded to the wiki. Use the following markup convention to reference them:
  • [[image:GrooperIcon_ObjectName.png]]
• Ex: This is the first time we've mentioned a Lexicon. So we linked to it and prepended its icon to it. But if we mention Lexions afterwards, we don't need to link to it.

Grooper ZIPs

Include links to download Grooper content the reader can import into their own Grooper environments.

• Use the following information box format:

{|class="download-box" | [[File:Asset 22@4x.png]] | You may download the ZIP(s) below and upload it into your own Grooper environment (version 2023). The first contains one or more '''Batches''' of sample documents. The second contains one or more '''Projects''' with resources used in examples throughout this article. * [[Media:2023_Wiki_Article-Name_Batches.zip]] * [[Media:2023_Wiki_Article-Name_Projects.zip]] |}

You may download the ZIP(s) below and upload it into your own Grooper environment (version 2023). The first contains one or more Batches of sample documents. The second contains one or more Projects with resources used in examples throughout this article. Media:2023_Wiki_Article-Name_Batches.zip Media:2023_Wiki_Article-Name_Projects.zip

Where does this box go?

• This should be the first thing the reader sees before the first level 2 heading (usually the "About" section).

Should this be configured or unconfigured content?

• This content should be configured content.
• The only exception is for resources such as CMIS Connections that contain sensitive connection info to external systems. Either do not include this content in the ZIP or leave it unconfigured.

How many Grooper ZIPs should I include?

• Most typically you will link to a maximum of two (2) files:
• One Grooper ZIP for Batches containing any documents shown in the article. Use the following naming format:
  • VersionNumber_Wiki_Article-Name_Batches.zip
• One Grooper ZIP for Projects containing any resources shown in the article. Use the following naming format:
  • VersionNumber_Wiki_Article-Name_Projects.zip

What if I have multiple Batches I need to upload?

• Put them in a folder in Grooper and export the folder.

What if I have multiple Projects I need to upload?

• Put them in a folder in Grooper and export the folder

What if I don't reference the Grooper UI in my article at all?

• In cases where articles do not reference the Grooper UI, you don't need to include a Grooper ZIP file.

What if I only have screenshots of one Batch?

• Size does not matter.
• Even if its just a single Batch with a single document, ZIP it up, and include it.

What if I only have screenshots of a single object, like just one Value Reader?

• Size does not matter.
• Even if it's a single node, put it in a Project, ZIP it up, and include it it.

Version control

The first line of any article should be the following:

• {{AutoVersion}}
• This inserts the version control toggle box at the top of any article.

All articles written in the most recent release version of Grooper will be written in the "Main" namespace. Articles written for older versions of Grooper will be migrated to a corresponding namespace as newer versions of Grooper are released.

• For example, imagine the current release version of Grooper is "2024" and an article about the Data Model object. The various "Data Model" articles for various versions would be named as below:
  • Data Model
  • 2023.1:Data Model
  • 2023:Data Model
  • 2022:Data Model
  • And so on

When a new version is released, articles currently in the Main namespace will be moved into a corresponding namespace.

• For example, imagine 2024 was just released. A new namespace will be created for 2023.1 articles. All articles currently in the Main namespace will be migrated to the new "2023.1" namespace.
• What about articles written for beta versions?
  • Typically, it is our internal policy to wait to document content until GA release.
  • In rare cases where we do need advance beta version documentation, there is a "Beta" namespace. Articles in the "Beta" namespace will be migrated to the Main namespace upon GA release.

BE AWARE: Moving an article to a different namespace can cause problems for our labeled section transclusion. When a GA release motivates a namespace move, we will need to take extra care to ensure transclusions work appropriately.

FYI: There may be a plan to prune older articles in the future but none has been implemented yet. Currently, articles from an EOL version do not show up in our standard search, but can be searched for using the advanced search.

Image naming convention

As we make more and more articles, we need a consistent way to name images that makes them easy to track down.

This naming convention must meet the following criteria:

• The Grooper version must be in the filename.
• The name of the article must be in the file name.
• The name needs to be short enough that the length of the path and filename do not exceed 256 characters.
  • This is an issue for BOTH where these images are stored in the Project Apollo SharePoint/OneDrive AND where these images are stored on the wiki server.
• The name needs to include some mechanism to navigate the section hierarchy of the article.

With these criteria in mind, our current naming convention is as follows:

• Ver# ArticleName Heading# Subheading# Subsubheading# ShortName ##.png

Imagine the following article with the following sections:

• 2023:Labeling Behavior
  • About
  • How To
    • Use Label Sets for Table Extraction
      • Label Sets and Tabular Layout
      • Label Sets and Row Match

The best file name for the fourth screenshot in the "Label Sets and Tabular Layout" section would be:

• 2023 LabelingBehavior 02 01 01 TabularLayout 04.png

"How To" screenshots

BE AWARE: As of Q4 2023, DO NOT use tabbed containers for screenshots. We are phasing out tabbed containers.

• Use full screen screenshots.
• Detail steps on the screenshot itself.
• Text steps should be typed above each screenshot.
• Don't crowd the screenshot with words.
  • Keep text brief and "to the point" on screenshots.
  • Use the text steps above the screenshot to explain further if needed.

Example screenshot with how to text:

1. With the Execute step selected, go to the "Activity Testing" tab.
2. Select the document from the "EDI Integration - Batch" in the Batch Viewer.
3. Click the "Test" button to test the activity and get extraction results.

On multiple screenshots & numbering

When you have multiple screenshots in your how-to instructions you have two options regarding numbering the steps in each shot.

1. Start over at "1" for each screenshot.
   • This is the "standard" way of doing things. It breaks instruction into smaller sets of instructional sequences rather than a long continuous sequence.
   • Before each sequence of steps, title it something to guide the user using the following format.
     • <big>'''Title for steps'''</big>
   • See "Example 1" below for an example.
2. Continue numbering each screenshot in sequence.
   • This is the "non-standard" way of doing things. It is up to the authors discretion whether it is appropriate.
   • The Good: This can be a good option if you have a small number of steps, particularly when the second screenshot only has one step on it.
   • The Bad: This is more tedious when you have lots of steps and screenshots. Each set of steps must be renumbered after each screenshot with the following format:
     • #<li value=num> The bullet is re-numbered whatever "num" is set to.
     • It can be difficult to keep track of numbering between editing wiki markup and editing the screenshot in Photoshop.
   • The Ugly: Do not use this approach when you have 10+ steps. Break steps up into groups of steps to make it easier for the reader to consume.
   • See "Example 2" below for an example.

On multiple screenshots & spacing

When you have multiple screenshots, be sure to leave an extra space after each screenshot and before the next set of how-to instructions. See below for how this would look in the markup:

<big>'''First set of instructions'''</big>
# Do this
# Then do this

[[image:2023_Example_06_01_OnMultipleScreenshots-01.png]]


<big>'''Next set of instructions'''</big>
# Next do this
# Last to this

[[image:2023_Example_06_01_OnMultipleScreenshots-02.png]]