2023:Article Template: Difference between revisions

From Grooper Wiki
← Older edit
 
(26 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.


'''Standards'''
'''''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.'''''
{|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]]
|}


When writing and reviewing your articles please stick to the following standards:
<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.


* Proper spelling and grammar
== First Section: What is it? ==
* Link internal Wiki articles and external links
** 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''


* 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'''.


== About ==
'''''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.
*Screenshots and images are highly encouraged here to aid your explanation.  Most people learn better with visual aids.
* Explain why people use this feature.
**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.
** What problem does it solve?
*This section should be mostly conceptual. The "Use Cases" and "How To" section can reinforce your explanation here with specifics.
** 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.


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


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


Use Cases provide specific context of how the topic is applied in the "real world".  Here you can detail solutions the topic addresses.
== Third Section: How do I set it up? (Or for UI Elements - How do I use it?) ==
*Screenshots can be very helpful here.
**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.
*Include multiple examples when possible.


== How To ==
<big>For configuration objects</big>
* 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.


=== How do I use it? ===
'''''Must include supademos for each configuration scenario. This is likely to be the most supademo heavy section.'''''


Here, guide your readers through configuring Grooper to solve a problem around the topic.
<big>For UI Elements</big>
*Set goals.  Explain what the problem is, what the desired result is, and how the topic addresses it before getting into configuration specifics
* Explain how to interact with the UI element.
*These instructions should guide the reader step by step of how to do something in Grooper.
* All UIs exist to do help a user do something. Explain how you use it to do that thing.
**Number your steps to keep readers on the right path.
* You must include at least describe its most "basic" or "standard" use.
**Show.  Don't tell.  Use screenshots to show the reader what they will see in Grooper.
* For more complicated features, this section will likely result in several sub-sections detailing different ways the UI is used.
*You can have as many "How Tos" as necessary in this section.
**If a single set of instructions starts to get complicated, with many many steps involved, break it up into a series of How Tos.
*Make use of the "Tab Container" to provide step-by-step guidance to readers.
**The first step should be "Prereqs".  Here, you can list any steps necessary to complete before you get into your instructions.
**For more information on configuring the "Tab Container" visit the [[Writing Articles#Tabbed Containers]] article.


== Version Differences ==


As Grooper improves, its implementation changes. If a new version changes how a topic is configured, it should be pointed out here.
''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}''


Version Guidance
== Fourth Section: Examples ==
*All articles should be written from the perspective of the current release version of Grooper.
* Showing how to configure something is a necessary part of learning how to implement Grooper features. But it doesn't show what they do.
**If an article needs to be adjusted or rewritten to reflect changes in a new version, the article should be renamed with the version indexed at the end of its title.
* All articles should have at least one example of what the feature does.
***i.e. If this article changed from version 2.72 to 2.80, the "Article Template" article pertaining to version 2.72 should be renamed to "Article Template (2.72)" and the new article updated to version 2.80 would be simply named "Article Template"
* Figure out a way to show users the '''effect''' of a feature.
*The article pertaining to the older version should then be linked in this section.  This way users of older versions can still get guidance.
** 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
**This doesn't mean you have to start from scratch on an article. When possible, you will simply copy the old versions article and make adjustments to reflect the changes.
** 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.


Example:
== Version Differences ==


In version 2.80, we changed our guidance on detailing property details in an object's property grid when writing articles.
As Grooper improves, its implementation changes.  If a new version changes how a topic is configured, it should be pointed out here.
 
=== Version Links ===
 
*[[Article Template - 2.72]]


== Property Details ==
''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.''
This section expands on the Grooper documentation for various Grooper object properties.


Here, you should explain more esoteric property details. This is most often helpful for properties that are useful for a limited set of use cases and cannot be fully explained in the in-app Help Documentation.
'''Wiki Article Versioning Guidance'''
*If a property is critical to a solution's configuration, it should be explained in one of the "How To" section's tutorials.
*All new articles should be written from the perspective of the '''''current''''' release version of Grooper.
*If the in-app Help Documentation for a property detail is not adequate, coordinate with the Dev team to make it so.
** 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 <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:
** [[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:


*[[Formatting Articles]]
<big>See Also</big>
* [[Article Formatting]]
* [[Article Standards]]
<big>Derived Types</big>
* Derived Type link 1
* Derived Type link 2
* Derived Type link 3
<big>Used By</big>
* Used by link 1
* Used by link 2


[[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"