View source for Article Standards

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

{|class="attn-box"
|
&#9888;
|
'''''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 ==
<big>Be proper</big>

Always use proper spelling and grammar.

<big>Be accurate</big>

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.

<big>Double spacing vs single spacing</big>

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.

<big>Capitalization</big>

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

<big>Letter case for section headings</big>

Starting Q3 2024, we will use [https://en.wikipedia.org/wiki/Letter_case#Sentence_case 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 <span style="background-color:yellow">'''''Extractor'''''</span> property.
** This includes groups of properties in a property grid.
**: Example:  Expressions can be configured in a '''Data Field's''' <span style="background-color:yellow">'''''Behavior'''''</span> properties.
** This includes anything in Grooper that has sub-properties as well.
*** Example: <span style="background-color:yellow">'''''Pattern Match'''''</span> 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''''' ('''''<span style="background-color:yellow">Recognize'''''</span> etc)
**** All '''''Extractor Types''''' ('''''<span style="background-color:yellow">Labeled Value'''''</span> etc)
**** All '''''Collation Providers''''' ('''''<span style="background-color:yellow">Ordered Array'''''</span> etc)
**** All '''''Table Extract Methods''''' ('''''<span style="background-color:yellow">Tabular Layout'''''</span> etc)
**** All '''''Behaviors''''' ('''''<span style="background-color:yellow">Labeling Behavior''''' etc)
** This includes larger categories of Grooper functionality as well.
*** Example: '''''Pattern Match''''' is an <span style="background-color:yellow">'''''Extractor Type'''''</span>
**** 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:
**** '''''<span style="background-color:yellow">Activity</span>'''''
**** '''''<span style="background-color:yellow">Behavior</span>'''''
**** '''''<span style="background-color:yellow">Table Extract Method</span>'''''
**** '''''<span style="background-color:yellow">Collation Provider</span>'''''
* '''''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 <span style="background-color:yellow">''200''</span>



Tabs in the Grooper UI should be enclosed in "quotes".
* Example:  Go to the '''Content Model's''' <span style="background-color:yellow">"Labels"</span> tab.

== Links ==
=== General link formatting ===
Always link to internal Grooper Wiki articles using the <code><nowiki>[[Article Name]]</nowiki></code> syntax. Ex:
* [[Tabular Layout]]
* <code><nowiki>[[Tabular Layout]]</nowiki></code>


For external links either:
* Use the full text syntax (aka "bare link")
** https://www.grooper.com
** <code><nowiki>https://www.grooper.com</nowiki></code>
* Or, use the nickname syntax (aka "nickname link")
** [https://www.grooper.com Grooper]
** <code><nowiki>[https://www.grooper.com Grooper]</nowiki></code>
* '''''NEVER''''' use the footnote syntax (aka "annotation link")
** [https://www.grooper.com]
** <code><nowiki>[https://www.grooper.com]</nowiki></code>

=== "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:
** <code><nowiki>[[image:GrooperIcon_ObjectName.png]]</nowiki></code>
* Ex: This is the first time we've mentioned a [[image:GrooperIcon_Lexicon.png]] '''[[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:
{|
|
<pre>
{|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]]
|}
</pre>
|
{|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]]
|}
|}

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:
** <code>VersionNumber_Wiki_Article-Name_Batches.zip</code>
* One Grooper ZIP for '''Projects''' containing any resources shown in the article. Use the following naming format:
** <code>VersionNumber_Wiki_Article-Name_Projects.zip</code>


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:
* <code><nowiki>{{AutoVersion}}</nowiki></code>
* 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 ==

{{#lst:Article Formatting|img_naming_convention}}

== Supademo standards ==

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

<big>Standard 1: Keep step by step text instructions in the article</big>
* 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.

<big>Standard 2: Link to the supademo before the step-by-step instructions.</big>
*<li class="attn-bullet"> 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.

<big>Standard 3: All demos' Step 1 should use the same template</big>
* 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.

<big>Standard 4: All callouts should default to "Grooper orange"</big>
* 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).

<big>Standard 5: All demos' final step should be the "Thank you for watching!" image</big>
* This is the image Randall Kinard made with the text under the Grooper logo.
* No voiceover is necessary. Keep it clean and quiet.

<big>Standard 6: Keep text on screen brief</big>
* Use the AI Voiceover to add more instruction/guidance when necessary.

<big>Standard 7: Keep zooms and pans to a minimum</big>
* 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.

<big>Standard 8: Only two hotspots max</big>
* 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.''

<big>Standard 9: Use Roboto for the font</big>
* Find this in the "Settings"

<big>Standard 10: Title it and give it a description</big>
* 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.

<big>Standard 11: General hotspot guidance</big>
* 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.

<big>Standard 12: Take Grooper screenshots in full screen.</big>
* Ensure all screenshots are screenshots 1920 x 1080 (even for screenshots outside of Grooper UI)
* FYI: That aspect ratio is 16:9.

<big>Standard 13: Use Bria for the AI Voiceover</big>
* This is the default.
* She's nice

<!-- EDITOR'S REMOVAL: We no longer do "How To" screenshots. Refer to "Supademo standards" instead

== "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.


<big>'''Example screenshot with how to text:'''</big>

# With the '''''Execute''''' step selected, go to the "Activity Testing" tab.
# Select the document from the "EDI Integration - Batch" in the Batch Viewer.
# Click the "Test" button to test the activity and get extraction results.
[[image:2023.1_XML-Schema-Integration_02_How-To_05.png]]

=== 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.
# 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.
#** <code><nowiki><big>'''Title for steps'''</big></nowiki></code>
#* See "Example 1" below for an example.
# 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:
#** <code><nowiki>#<li value=num> The bullet is re-numbered whatever "num" is set to.</nowiki></code>
#** 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.

==== Example 1: Starting over at "1" for each screenshot ====
<pre>
<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]]
</pre>

==== Example 2: Continue numbering in sequence ====
<pre>
# Do this
# Then do this

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


#<li value=3> Next do this
# Last to this

[[image:2023_Example_06_01_OnMultipleScreenshots-02.png]]
</pre>

=== 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:

<pre>
<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]]
</pre>

EDITOR'S REMOVAL We no longer do "How To" screenshots. Refer to "Supademo standards" instead--->