Article Template

From Grooper Wiki
Jump to navigation Jump to search
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.

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.

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

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

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

Version Guidance

  • All articles should be written from the perspective of the current release version of Grooper.
    • 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.
      • 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"
  • The article pertaining to the older version should then be linked in this section. This way users of older versions can still get guidance.
    • 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:

In version 2.80, we changed our guidance on detailing property details in an object's property grid when writing articles.

Version Links

Grooper Help Documentation

Here, link directly to the Help Documentation for the object in question


  • If that property is critical to a solution's configuration, it should be explained in one of the "How To" section's tutorials.
  • If the Help Documentation for a property detail is not adequate, send an email to the Dev team.

See Also

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

Example: