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

Be proper

Always use proper spelling and grammar.

Be accurate

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 vs single spacing

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

Capitalization

All Grooper objects and properties should be capitalized. Exceptions to this rule are documented in the Grooper Colloquialisms article.

Letter case for section headings

Starting Q3 2024, we will use sentence case for all section headings. Sentence case is the standard for Wikipedia. It better distinguishes between proper nouns (objects and properties in the formal Grooper vocabulary) and other words.

Capitalize ONLY the first letter of the section's title and any proper nouns.
All Grooper objects and properties should be capitalized. Exceptions to this rule are documented in the Grooper Colloquialisms article.

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.
  Example: A Value Reader only has one configurable property, the Extractor property.
- This includes groups of properties in a property grid.
  Example: Expressions can be configured in a Data Field's Behavior properties.
- This includes anything in Grooper that has sub-properties as well.
  - Example: Pattern Match is an Extractor Type.
    - It is not a Grooper object. So, it should not be bolded.
    - Rather, Pattern Match is one of many things in Grooper that brings up a configurable set of properties once selected.
  - Other examples include:
    - All Activities (Recognize etc)
    - All Extractor Types (Labeled Value etc)
    - All Collation Providers (Ordered Array etc)
    - All Table Extract Methods (Tabular Layout etc)
    - All Behaviors (Labeling Behavior etc)
- This includes larger categories of Grooper functionality as well.
  - Example: Pattern Match is an Extractor Type
    - It is not a specific Grooper object. So, it should not be bolded.
    - These may or may not be a configurable property. But they are a category of various things in Grooper that are configured with a property grid.
  - Other examples include:
    - Activity
    - Behavior
    - Table Extract Method
    - Collation Provider
If you are unsure if something should be bolded or bold italicized, there's a good bet it should be bold italicized.

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

Example: On the Data Field, set the Display Width to 200

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

Example: Go to the 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.

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

Supademo standards

Starting in version 2025, "how to" screenshots are replaced with supademos.

Standard 1: Keep step by step text instructions in the article

Text is necessary for the HelpSearch resource that AI Assistants use in Grooper.
More advanced users will just want to refer to the text-based steps anyway.
Refer to Project (Object)#Adding a New Project for an example.

Standard 2: Link to the supademo before the step-by-step instructions.

BE AWARE! This will change once we add the capability to embed ifra

mes into the wiki articles.

Refer to Project (Object)#Adding a New Project for an example.

Standard 3: All demos' Step 1 should use the same template

This is the editable PowerPoint template made by Randall Kinard. Edit the template with the section heading and title of the demo. Export a png. Upload it as the first step for the demo.
Keep the text right aligned.
Make sure this step has no voice over.
Include a "Callout" hotspot with the text "Click the arrow to begin." or "Click here to begin"
Make sure the callout is generally in the lower left corner.

Standard 4: All callouts should default to "Grooper orange"

Grooper orange = #f89420
Grooper orange is for instructions.
Grooper teal = #36b0a7
Grooper teal callouts are for "FYI" or additional info.
Grooper teal callouts should be used rarely and with purpose (Don't just do it all the time. It gets in the way).

Standard 5: All demos' final step should be the "Thank you for watching!" image

This is the image Randall Kinard made with the text under the Grooper logo.
No voiceover is necessary. Keep it clean and quiet.

Standard 6: Keep text on screen brief

Use the AI Voiceover to add more instruction/guidance when necessary.

Standard 7: Keep zooms and pans to a minimum

In general, the zooms and pans supademo likes to add are distracting. It can make it easy for viewers to loose their place in the Grooper UI.
Only zoom when you have a reason to do it. If it helps instruct the user, go for it. Otherwise, don't do it.
When it doubt, don't zoom.

Standard 8: Only two hotspots max

Multiple hotspots can help reduce the number of steps in the demo. This is usually a good thing.
Multiple hotspots can obscure the UI. With more than two on the screen, it can be confusing what to read first (second, third, fourth, etc). This is bad.
When you want to use multiple hotspots, stick with two.
Hide the arrows on the first hotspot.
- Supademo always makes the first hotspot CREATED animated. You may need to delete/recreate hotspots in order to get the animation order the way you want.
MAYBE three hotspots is ok. This will take some experimentation on our part. We all agree four is definitely too much.

Standard 9: Use Roboto for the font

Find this in the "Settings"

Standard 10: Title it and give it a description

In the description, don't worry too much about SEO (that's marketing's job) but including "Grooper" in the description text will help.
Keep the description short and sweet.

Standard 11: General hotspot guidance

Use "Pointer Hotspot" for right-clicks in Grooper.
Use "Custom Area Hotspot" for pretty much everything else.
Use "Callout Hotspot" when you're not pointing to anything on the screen.

Standard 12: Take Grooper screenshots in full screen.

Ensure all screenshots are screenshots 1920 x 1080 (even for screenshots outside of Grooper UI)
FYI: That aspect ratio is 16:9.

Standard 13: Use Bria for the AI Voiceover

This is the default.
She's nice