Difference between revisions of "Contributing to the Wiki"

From PegaWiki
Jump to navigation Jump to search
(updated Wiki name)
Tag: Visual edit
(Updated with guidance on writing good titles and clear content.)
Tag: Visual edit
Line 1: Line 1:
Pega Community Wiki depends on your participation! If you have a design pattern to share, please add it AND expect your colleagues to make edits or suggestions.  
+
{{Design pattern|Title=Contributing to the Wiki|Description=Simple guidance on contributing to the Pega Community Wiki|Version=8.5|Applications=Platform|Capability Area=Platform|Owner=Mosczynski, jane}}
 +
 
 +
== It's a group effort! ==
 +
Pega Community Wiki depends on your participation! If you have a design pattern to share, go ahead and add it! You should also expect that your colleagues might make edits or suggestions.  
  
 
=== What's the difference between an edit and a suggestion? ===
 
=== What's the difference between an edit and a suggestion? ===
Edits are added directly to a design pattern. If you have additional content that would enhance the design pattern or notice something that should be corrected, use the '''Edit''' function. For example, ''Making pizza in high altitudes'' may be added to the ''Making Pizza'' design pattern. '''Note''': Edits are currently available for Pega employees and will be curated prior to publishing.  
+
Edits are made directly to a design pattern. If you have additional content that would enhance the design pattern, or notice something that should be corrected, use the '''Edit''' function. For example, a section on ''Making pizza at high altitudes'' could be added to the ''Making Pizza'' design pattern. '''Note''': Editing is currently available to Pega employees and will be curated prior to publishing.
 +
 
 +
'''Suggestions''' provide a forum for recommendations and questions. For example, "This is helpful, but it would be great to have details on how to make pizza dough at a high altitude," or "What types of tomatoes are recommended for a great pizza sauce?" '''Note''': Suggestions can currently only be made by Pega employees. Moving into phase two, we will be opening up this feature for authenticated users.
  
Suggestions provide a forum for recommendations and questions. For example, "This is helpful, it would be great to have details on how to make pizza dough at a high altitude." or "What types of tomatoes are recommended for a great pizza sauce?" '''Note''': Currently Suggestions are only available for Pega employees. Moving into phase two, we will be opening up this feature for authenticated users.
+
== Writing guidelines ==
 +
In your writing, there are three simple guidelines that will help you create the best possible content:
 +
* Be clear: Use simple sentences to communicate. Avoid uncertainty when providing instructions.
 +
* Be specific: Write exactly what you need to communicate. Be precise and only include the necessary details.
 +
* Be consistent: Your style, structure, format, and use of terms should be consistent.
  
=== Writing guidelines ===
+
=== Content to avoid! ===
Please review and follow these guidelines to ensure that Pega Community Wiki is a healthy, vibrant community.
+
Review and follow these guidelines to ensure that Pega Community Wiki is a healthy, vibrant community.
  
 
Pega Community Wiki content '''should not''' include:
 
Pega Community Wiki content '''should not''' include:
Line 19: Line 28:
 
* Commentary or subjective opinion on products of other vendors or the vendors themselves
 
* Commentary or subjective opinion on products of other vendors or the vendors themselves
 
* Quotes containing commentary or subjective opinion on products of other vendors or the vendors themselves
 
* Quotes containing commentary or subjective opinion on products of other vendors or the vendors themselves
Design pattern titles
 
  
Use action verbs in titles. Example: Making white sauce for pizza. Non example: Best practices for white pizza sauce.
+
=== Writing good titles ===
 +
Titles give the essence of the information that a user is about to digest. Giving your article an attractive, interesting title is a key part of the writing process. The following simple guidelines can help you to create good titles:
 +
* <u>Do not write "Best practices for..."</u>, as this creates problems with the Wiki engine's sorting and display of articles.
 +
* Capitalization: Use sentence-style capitalization (capital letter on the first word and proper names), not headline style (capital letters on every word).
 +
* Length: Long-winded titles look bad and risk becoming incomprehensible. Provide enough information, but don't try to summarize the entire topic in the title.
 +
* Action verbs: Use active voice and positive statements to give your titles impact. For example:  
 +
** '''Good:''' ''Making white sauce for pizza''. '''Bad:''' ''Best practices for white pizza sauce''.
 +
** '''Good:''' ''Diagnosing your system with the Performance tool'' '''Bad:''' ''Use the Performance tool'' ''to diagnose your system''
 +
** '''Good:''' Migrating customer data from Salesforce to Pega Sales Automation '''Bad:''' Ways to migrate customer data from Salesforce to Pega Sales Automation
  
=== Need support or have questions? ===
+
== Need support or have questions? ==
 
Contact the [mailto:PegaWikisupport@pega.com PegaWiki team]
 
Contact the [mailto:PegaWikisupport@pega.com PegaWiki team]

Revision as of 09:04, 27 October 2020

Contributing to the Wiki

Description Simple guidance on contributing to the Pega Community Wiki
Version as of 8.5
Application Platform
Capability/Industry Area Platform



It's a group effort![edit]

Pega Community Wiki depends on your participation! If you have a design pattern to share, go ahead and add it! You should also expect that your colleagues might make edits or suggestions.

What's the difference between an edit and a suggestion?[edit]

Edits are made directly to a design pattern. If you have additional content that would enhance the design pattern, or notice something that should be corrected, use the Edit function. For example, a section on Making pizza at high altitudes could be added to the Making Pizza design pattern. Note: Editing is currently available to Pega employees and will be curated prior to publishing.

Suggestions provide a forum for recommendations and questions. For example, "This is helpful, but it would be great to have details on how to make pizza dough at a high altitude," or "What types of tomatoes are recommended for a great pizza sauce?" Note: Suggestions can currently only be made by Pega employees. Moving into phase two, we will be opening up this feature for authenticated users.

Writing guidelines[edit]

In your writing, there are three simple guidelines that will help you create the best possible content:

  • Be clear: Use simple sentences to communicate. Avoid uncertainty when providing instructions.
  • Be specific: Write exactly what you need to communicate. Be precise and only include the necessary details.
  • Be consistent: Your style, structure, format, and use of terms should be consistent.

Content to avoid![edit]

Review and follow these guidelines to ensure that Pega Community Wiki is a healthy, vibrant community.

Pega Community Wiki content should not include:

  • Personal content
  • Customer references
  • Customer names
  • Competitor references
  • Competitor names
  • Company confidential information
  • Commentary or subjective opinion on products of other vendors or the vendors themselves
  • Quotes containing commentary or subjective opinion on products of other vendors or the vendors themselves

Writing good titles[edit]

Titles give the essence of the information that a user is about to digest. Giving your article an attractive, interesting title is a key part of the writing process. The following simple guidelines can help you to create good titles:

  • Do not write "Best practices for...", as this creates problems with the Wiki engine's sorting and display of articles.
  • Capitalization: Use sentence-style capitalization (capital letter on the first word and proper names), not headline style (capital letters on every word).
  • Length: Long-winded titles look bad and risk becoming incomprehensible. Provide enough information, but don't try to summarize the entire topic in the title.
  • Action verbs: Use active voice and positive statements to give your titles impact. For example:
    • Good: Making white sauce for pizza. Bad: Best practices for white pizza sauce.
    • Good: Diagnosing your system with the Performance tool Bad: Use the Performance tool to diagnose your system
    • Good: Migrating customer data from Salesforce to Pega Sales Automation Bad: Ways to migrate customer data from Salesforce to Pega Sales Automation

Need support or have questions?[edit]

Contact the PegaWiki team