2023:Article Template: Difference between revisions

From Grooper Wiki
← Older edit
No edit summary
Tag: visualeditor-switched
 
(16 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[File:Grooper TM 1.png|thumb|An image at the top of the article is a good visual to identify your topic.]]
'''''BE AWARE:''' The first line of any article should be'' <code><nowiki>{{AutoVersion}}</nowiki></code> ''This creates the version control box below.''
{{AutoVersion}}


<blockquote style="font-size:14pt">
[[File:Grooper TM 1.png|thumb|200px|An image at the top of the article is a good visual to identify your topic. <code>thumb</code> tagged images can be reduced in size (but not enlarged). <code>frame</code> tagged images cannot be size adjusted.]]
Start with a quick one to two sentence "glossary" style definition of the subject to introduce the topic here.
 
<blockquote>
Start with a quick one to three sentence "glossary" style definition of the subject to introduce the topic here. The glossary term should be added to the [[Glossary]] page and transcluded from there.
</blockquote>
</blockquote>


Expand the introduction here with a few more sentences if necessary. This introductory section should be no longer than a paragraph.  More in-depth explanation of the topic should be done in the "About" section.
Optional: Expand the introduction here with a few more sentences (only if necessary). Longer "about" or "overview" information should be included in the article's first major section heading.
*Keep the introduction brief.
*Avoid detailing specific configurations.  There are other sections for that.
*While giving simple examples can help readers understand the concept, avoid overly detailed explanations of use cases.  There are other sections for that.
*The ONLY image in this section should be a general image pertaining to the topic in the top right corner.  If you need an image to explain your topic (which is highly encouraged!), use it in a different section.


 
'''''All articles should include Grooper ZIP files. ZIP files should be linked at the start of the article '''before''' the first section heading. Use the "download-box" style to call out downloads like the one below. See the [[Article Standards]] for more specifics on Grooper ZIP standards.'''''
Always include links to download Grooper content the reader can import into their own Grooper environments.
* This should be the first thing the reader sees before the first level 2 heading (the "About" section).
* 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 Batches - Wiki - Article Name.zip</code>
** One Grooper ZIP for Projects containing any resources shown in the article.  Use the following naming format:
*** <code>VersionNumber Projects- Wiki - Article Name.zip</code>
* The ''only'' exception is for resources such as '''CMIS Connections''' that contain sensitive connection info to external systems.
* Use the following information box to call out the downloads:
{|cellpadding=10 cellspacing=5
|
'''Markup Text'''
|
'''Rendered in Wiki'''
|-
|
<pre>
{|class="download-box"
{|class="download-box"
|-
|
|
[[File:Asset 22@4x.png]]
[[File:Asset 22@4x.png]]
|
|
You may download and import the files below into your own Grooper environment (version 2023). The first contains a '''Project''' with several '''Content Models''' used as examples throughout this article.  The second contains some example '''Batches''' of sample documents.
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:V23 Project - Wiki - Style_Sheets.zip]]
* [[Media:2023_Wiki_Article-Name_Batches.zip]]
* [[Media:V23 Batches - Wiki - Style_Sheets.zip]]
* [[Media:2023_Wiki_Article-Name_Projects.zip]]
|}
</pre>
|
{|class="download-box"
|-
|
[[File:Asset 22@4x.png]]
|
You may download and import the files below into your own Grooper environment (version 2023).  The first contains a '''Project''' with several '''Content Models''' used as examples throughout this article.  The second contains some example '''Batches''' of sample documents.
* [[Media:V23 Project - Wiki - Style Sheets.zip]]
* [[Media:V23 Batches - Wiki - Style Sheets.zip]]
|}
|}
|}


== About ==
<big>A note on sections in articles</big>
* Use sections (h2) to break up information in your article.
* Use sub-sections (h3, h4, etc) to further break up complex information into more consumable (and linkable) parts.
* While we have gone away from a rigidly prescribed section structure in our articles, the following 4 sections should likely be included in each article, in some way.
 
== First Section: What is it? ==
 
* Tell the reader what the feature/configuration object is.
* Explain what it does.
* This section is for overviewing the feature. It should be a "view from above" or "at a glance" in terms of detail. Include enough information so the reader can generally understand the feature's '''function'''.
 
'''''Include screenshots, illustrations or a small supademo to overview what the feature is.'''''


'''How does it work?'''
''You may name this section whatever you think is most appropriate. Or just name it "What is {ArticleTopic}?"''
== Second Section: What is it for? ==


If you can't adequately explain the topic in the introductory paragraph, the "About" section will allow you to expand.  What differentiates the Wiki from the is the Wiki answers "How? and Why?" where the Help Documentation answers "What?".  Help Documentation explains "what" something is in Grooper.  Wiki articles should expand this to "how" something functions and is used.  The About section expands on how something works in Grooper.  You can't always get a good idea of how something works in Grooper with the description given in the help documentation.  The About section gives you more room to demonstrate how something works.
* Tell the reader how the feature/configuration object is used.
* This should be a high level/general explanation.  
* Explain why people use this feature.
* Visual aids are encouraged, including:
** What problem does it solve?
** Diagrams
** If it prepares content for downstream processing, what is it doing and how does it help?
** Document screenshots
* When possible, include overviews of practical use cases implementing the feature. How to users actually use this in the real world?
*** Be sure all documents are "public facing". They cannot come from a client or have personal data.  Use public records or mocked up documents.
* This section is about helping the reader understand the feature's utility and usefulness. If a user doesn't understand a feature's '''purpose''', they are less likely to use it and more likely to misuse it.
** Grooper UI screenshots
*Screenshots and images are highly encouraged here to aid your explanation.  Most people learn better with visual aids.
*This section should be mostly conceptual. The "How To" and "Use Cases" section can reinforce your explanation here with specifics.


== How To ==
'''''Include screenshots, illustrations or a small supademo to overview the feature's use.'''''


'''How do I use it?'''
''You may name this section whatever you think is most appropriate. Or just name it "What is {ArticleTopic} used for?"''


Here, guide your readers through configuring Grooper to solve a problem around the topic.
== Third Section: How do I set it up? (Or for UI Elements - How do I use it?) ==
*Set goals.  Explain what the problem is, what the desired result is, and how the topic addresses it before getting into configuration specifics
*These instructions should guide the reader step by step of how to do something in Grooper.
**Number your steps to keep readers on the right path.
**Show.  Don't tell.  Use screenshots to show the reader what they will see in Grooper.
*You can have as many "How To" sections as necessary.
**If a single set of instructions starts to get complicated, with many many steps involved, break it up into a series of How Tos.


* Current screenshot guidance:
<big>For configuration objects</big>
** Use full screen screenshots.
* Explain how to configure the feature.
** Detail steps on the screenshot itself.
* You must include at least describe the most "basic" or "standard" configuration.
** Text steps should be typed ''above'' each screenshot.
* For more complicated features, this section will likely result in several sub-sections detailing different configuration scenarios.
** Don't crowd the screenshot with words.  Keep text breif and "to the point" on screenshots. Use the text steps ''above'' the screenshot to explain further if needed.


Example:
'''''Must include supademos for each configuration scenario. This is likely to be the most supademo heavy section.'''''


# With the "Execute" '''Batch Process Step''' selected, go to the "Activity Testing" tab.
<big>For UI Elements</big>
# Select the document from the "EDI Integration - Batch" in the Batch Viewer.
* Explain how to interact with the UI element.
# Click the "Test" button to test the activity and get extraction results.
* All UIs exist to do help a user do something. Explain how you use it to do that thing.
[[image:2023.1_XML-Schema-Integration_02_How-To_05.png]]
* You must include at least describe its most "basic" or "standard" use.
* For more complicated features, this section will likely result in several sub-sections detailing different ways the UI is used.


== Use Cases ==


'''Why do I need it?'''
''You may name this section whatever you think is most appropriate. Or just name it "How to set up {ArticleTopic}" or "How to use {ArticleTopic}''


Use Cases provide specific context of how the topic is applied in the "real world". Here you can detail solutions the topic addresses.
== Fourth Section: Examples ==
*This should be a more specific/example driven explanation.
* Showing how to configure something is a necessary part of learning how to implement Grooper features. But it doesn't show what they do.
*Screenshots can be very helpful here.
* All articles should have at least one example of what the feature does.
**Be careful what images you use.  Any documents need to be "Public Facing", lacking any proprietary client or personal data.  Use public records or mocked up documents.
* Figure out a way to show users the '''effect''' of a feature.
*Include multiple examples when possible.
** Example: Don't just show users the "Recognize" activity by running the activity and calling it quits. Show them the text data that gets generated. Show them that extractors can now return text data. Show them
** Example: Don't just show users how to configure the "PDF Format" for Export and call it quits. Show them that PDF Format's place in an Export step. Show them the file that gets generated.
* Ideally, this will be a real-world or practical example (or multiple examples!).
* Even if the example is not the most practical, that's ok. User's seeing the results of a configuration helps them better understand what the feature does and its purpose.


== Version Differences ==
== Version Differences ==
Line 112: Line 86:
** For example, if this article was originally written for version 2.72 it would be moved into the 2.72 namespace and renamed "2.72:Article Template".
** For example, if this article was originally written for version 2.72 it would be moved into the 2.72 namespace and renamed "2.72:Article Template".
* Articles from older versions are linked at the top of each article thanks to the <code><nowiki>{{AutoVersion}}</nowiki></code> markup at the first line of the article.
* Articles from older versions are linked at the top of each article thanks to the <code><nowiki>{{AutoVersion}}</nowiki></code> markup at the first line of the article.
 
* If you need to link to an article from a specific version, be sure to include its namespace in the link.  The following would link to the 2.72 version of this article:
If you need to link to an article from a specific version, be sure to include its namespace in the link.  The following would link to the 2.72 version of this article:
** [[2.72:Article Template]]
* [[2.72:Article Template]]


== See Also ==
== See Also ==


Here, link to other articles in the wiki related to the topic or appropriate external links.
You are not required to include this section. But it can help point users to other features and information on the wiki.
* Be sure to only include relevant links.
* Don't know what links to include? Check out the in-app Grooper Help page for the topic. If you see any '''Derived Types''' or '''Used By''' links at the bottom of that page, that's always good to include in this section.


Example:
Example:


<big>See Also</big>
* [[Article Formatting]]
* [[Article Formatting]]
* [[Article Standards]]
* [[Article Standards]]
 
<big>Derived Types</big>
'''Standards'''
* Derived Type link 1
 
* Derived Type link 2
When writing and reviewing your articles please stick to the following standards:
* Derived Type link 3
 
<big>Used By</big>
* Proper spelling and grammar
* Used by link 1
* Link internal Wiki articles and external links
* Used by link 2
** 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.
** Visit the [[Formatting Articles#Links]] page for more information.
* Bold all Grooper '''objects'''
* Bold and Italicize all Grooper '''''properties'''''
* Italicize all Grooper property ''settings''
** I.E.  On the '''Data Field''', set the '''''Alignment''''' property to ''Right''


[[Category:Style Guide]]
[[Category:Style Guide]]

Latest revision as of 09:26, 28 October 2025

BE AWARE: The first line of any article should be {{AutoVersion}} This creates the version control box below.

This article is about an older version of Grooper.

Information may be out of date and UI elements may have changed.

202520232.72
An image at the top of the article is a good visual to identify your topic. thumb tagged images can be reduced in size (but not enlarged). frame tagged images cannot be size adjusted.

Start with a quick one to three sentence "glossary" style definition of the subject to introduce the topic here. The glossary term should be added to the Glossary page and transcluded from there.

Optional: Expand the introduction here with a few more sentences (only if necessary). Longer "about" or "overview" information should be included in the article's first major section heading.

All articles should include Grooper ZIP files. ZIP files should be linked at the start of the article before the first section heading. Use the "download-box" style to call out downloads like the one below. See the Article Standards for more specifics on Grooper ZIP standards.

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.

A note on sections in articles

  • Use sections (h2) to break up information in your article.
  • Use sub-sections (h3, h4, etc) to further break up complex information into more consumable (and linkable) parts.
  • While we have gone away from a rigidly prescribed section structure in our articles, the following 4 sections should likely be included in each article, in some way.

First Section: What is it?

  • Tell the reader what the feature/configuration object is.
  • Explain what it does.
  • This section is for overviewing the feature. It should be a "view from above" or "at a glance" in terms of detail. Include enough information so the reader can generally understand the feature's function.

Include screenshots, illustrations or a small supademo to overview what the feature is.

You may name this section whatever you think is most appropriate. Or just name it "What is {ArticleTopic}?"

Second Section: What is it for?

  • Tell the reader how the feature/configuration object is used.
  • Explain why people use this feature.
    • What problem does it solve?
    • If it prepares content for downstream processing, what is it doing and how does it help?
  • When possible, include overviews of practical use cases implementing the feature. How to users actually use this in the real world?
  • This section is about helping the reader understand the feature's utility and usefulness. If a user doesn't understand a feature's purpose, they are less likely to use it and more likely to misuse it.

Include screenshots, illustrations or a small supademo to overview the feature's use.

You may name this section whatever you think is most appropriate. Or just name it "What is {ArticleTopic} used for?"

Third Section: How do I set it up? (Or for UI Elements - How do I use it?)

For configuration objects

  • Explain how to configure the feature.
  • You must include at least describe the most "basic" or "standard" configuration.
  • For more complicated features, this section will likely result in several sub-sections detailing different configuration scenarios.

Must include supademos for each configuration scenario. This is likely to be the most supademo heavy section.

For UI Elements

  • Explain how to interact with the UI element.
  • All UIs exist to do help a user do something. Explain how you use it to do that thing.
  • You must include at least describe its most "basic" or "standard" use.
  • For more complicated features, this section will likely result in several sub-sections detailing different ways the UI is used.


You may name this section whatever you think is most appropriate. Or just name it "How to set up {ArticleTopic}" or "How to use {ArticleTopic}

Fourth Section: Examples

  • Showing how to configure something is a necessary part of learning how to implement Grooper features. But it doesn't show what they do.
  • All articles should have at least one example of what the feature does.
  • Figure out a way to show users the effect of a feature.
    • Example: Don't just show users the "Recognize" activity by running the activity and calling it quits. Show them the text data that gets generated. Show them that extractors can now return text data. Show them
    • Example: Don't just show users how to configure the "PDF Format" for Export and call it quits. Show them that PDF Format's place in an Export step. Show them the file that gets generated.
  • Ideally, this will be a real-world or practical example (or multiple examples!).
  • Even if the example is not the most practical, that's ok. User's seeing the results of a configuration helps them better understand what the feature does and its purpose.

Version Differences

As Grooper improves, its implementation changes. If a new version changes how a topic is configured, it should be pointed out here.

This section is optional. Only outline important differences from in-support versions of Grooper. For example, if Grooper changed from version 2.90 to 2021 but 2.90 has reached EOL, you don't need to document the change in a 2024 article.

Wiki Article Versioning Guidance

  • All new articles should be written from the perspective of the current release version of Grooper.
    • Articles written in the Main wiki namespace are assumed to cover the current version.
  • Articles written for older versions are migrated to a namespace corresponding to their version number
    • For example, if this article was originally written for version 2.72 it would be moved into the 2.72 namespace and renamed "2.72:Article Template".
  • Articles from older versions are linked at the top of each article thanks to the {{AutoVersion}} markup at the first line of the article.
  • If you need to link to an article from a specific version, be sure to include its namespace in the link. The following would link to the 2.72 version of this article:

See Also

You are not required to include this section. But it can help point users to other features and information on the wiki.

  • Be sure to only include relevant links.
  • Don't know what links to include? Check out the in-app Grooper Help page for the topic. If you see any Derived Types or Used By links at the bottom of that page, that's always good to include in this section.

Example:

See Also

Derived Types

  • Derived Type link 1
  • Derived Type link 2
  • Derived Type link 3

Used By

  • Used by link 1
  • Used by link 2
Retrieved from "https://wiki.grooper.com/index.php?title=2023:Article_Template&oldid=31513"