2023:Article Template: Difference between revisions

From Grooper Wiki
← Older editNewer edit →
No edit summary
Tag: visualeditor-switched
Line 11: Line 11:
*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.
*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'''
When writing and reviewing your articles please stick to the following standards:
* Proper spelling and grammar
* 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''
== About ==
'''How does it work?'''
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.
* This should be a high level/general explanation.
*Screenshots and images are highly encouraged here to aid your explanation.  Most people learn better with visual aids.
**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.
*This section should be mostly conceptual.  The "Use Cases" and "How To" section can reinforce your explanation here with specifics.
== Use Cases ==
'''Why do I need it?'''
Use Cases provide specific context of how the topic is applied in the "real world".  Here you can detail solutions the topic addresses.
*This should be a more specific/example driven explanation.
*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 ==


'''How do I use it?'''
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).  
Here, guide your readers through configuring Grooper to solve a problem around the topic.
* Most typically you will link to a maximum of two (2) files:
*Set goals.  Explain what the problem is, what the desired result is, and how the topic addresses it before getting into configuration specifics
** One Grooper ZIP for Batches containing any documents shown in the article.  Use the following naming format:
*These instructions should guide the reader step by step of how to do something in Grooper.
*** <code>VersionNumber Batches - Wiki - Article Name.zip</code>
**Number your steps to keep readers on the right path.
** One Grooper ZIP for Projects containing any resources shown in the article.  Use the following naming format:
**Show.  Don't tell.  Use screenshots to show the reader what they will see in Grooper.
*** <code>VersionNumber Projects- Wiki - Article Name.zip</code>
*You can have as many "How Tos" as necessary in this section.
* The ''only'' exception is for resources such as '''CMIS Connections''' that contain sensitive connection info to external systems.
**If a single set of instructions starts to get complicated, with many many steps involved, break it up into a series of How Tos.
* Use the following information box to call out the downloads:
*Make use of the "Tab Container" to provide step-by-step guidance to readers.
**The first step should often 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.
*Always include links to download Grooper content the reader can import into their own Grooper environments. Use the following information box to call out the downloads:
{|cellpadding=10 cellspacing=5
{|cellpadding=10 cellspacing=5
|
|
Line 74: Line 35:
|
|
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 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 Project - Wiki - Style_Sheets.zip]]
* [[Media:V23_Batches_-_Wiki_-_Style_Sheets.zip]]
* [[Media:V23 Batches - Wiki - Style_Sheets.zip]]
|}
|}
</pre>
</pre>
Line 85: Line 46:
|
|
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 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 Project - Wiki - Style Sheets.zip]]
* [[Media:V23_Batches_-_Wiki_-_Style_Sheets.zip]]
* [[Media:V23 Batches - Wiki - Style Sheets.zip]]
|}
|}
|}
|}
== About ==
'''How does it work?'''
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.
* This should be a high level/general explanation.
* Visual aids are encouraged, including:
** Diagrams
** Document screenshots
*** Be sure all documents are "public facing".  They cannot come from a client or have personal data.  Use public records or mocked up documents.
** 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 ==
'''How do I use it?'''
Here, guide your readers through configuring Grooper to solve a problem around the topic.
*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:
** 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 breif and "to the point" on screenshots.  Use the text steps ''above'' the screenshot to explain further if needed.
Example:
# With the "Execute" '''Batch Process 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]]
== Use Cases ==
'''Why do I need it?'''
Use Cases provide specific context of how the topic is applied in the "real world".  Here you can detail solutions the topic addresses.
*This should be a more specific/example driven explanation.
*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.


== Version Differences ==
== Version Differences ==
Line 94: Line 104:
As Grooper improves, its implementation changes.  If a new version changes how a topic is configured, it should be pointed out here.
As Grooper improves, its implementation changes.  If a new version changes how a topic is configured, it should be pointed out here.


Version Guidance
''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.
*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 in the Main wiki namespace are assumed to cover the current version.
Line 103: Line 115:
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]]
== Property Details ==
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.
*If a property is critical to a solution's configuration, it should be explained in one of the "How To" section's tutorials.
*If the in-app Help Documentation for a property detail is not adequate, coordinate with the Dev team to make it so.


== See Also ==
== See Also ==
Line 117: Line 122:
Example:
Example:


*[[Formatting Articles]]
* [[Article Formatting]]
* [[Article Standards]]
 
'''Standards'''
 
When writing and reviewing your articles please stick to the following standards:
 
* Proper spelling and grammar
* 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''


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

Revision as of 10:01, 5 March 2024

An image at the top of the article is a good visual to identify your topic.

Start with a quick one to two sentence "glossary" style definition of the subject to introduce the topic here.

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.

  • 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.


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:
      • VersionNumber Batches - Wiki - Article Name.zip
    • One Grooper ZIP for Projects containing any resources shown in the article. Use the following naming format:
      • VersionNumber Projects- Wiki - Article Name.zip
  • 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:

Markup Text

Rendered in Wiki 

{|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]]
|}

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.

About

How does it work?

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.

  • This should be a high level/general explanation.
  • Visual aids are encouraged, including:
    • Diagrams
    • Document screenshots
      • Be sure all documents are "public facing". They cannot come from a client or have personal data. Use public records or mocked up documents.
    • 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

How do I use it?

Here, guide your readers through configuring Grooper to solve a problem around the topic.

  • 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:
    • 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 breif and "to the point" on screenshots. Use the text steps above the screenshot to explain further if needed.

Example:

  1. With the "Execute" Batch Process 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.

Use Cases

Why do I need it?

Use Cases provide specific context of how the topic is applied in the "real world". Here you can detail solutions the topic addresses.

  • This should be a more specific/example driven explanation.
  • 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.

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

Here, link to other articles in the wiki related to the topic or appropriate external links.

Example:

Standards

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

  • Proper spelling and grammar
  • 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
Retrieved from "https://wiki.grooper.com/index.php?title=2023:Article_Template&oldid=19504"