[DOCU-114] Commenting with EE and CE Created: 26/Jan/11  Updated: 30/Dec/14  Resolved: 30/Dec/14

Status: Closed
Project: Documentation
Component/s: content
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Neutral
Reporter: Antti Hietala Assignee: Antti Hietala
Resolution: Outdated Votes: 0
Labels: None
Σ Remaining Estimate: Not Specified Remaining Estimate: Not Specified
Σ Time Spent: Not Specified Time Spent: Not Specified
Σ Original Estimate: Not Specified Original Estimate: Not Specified

Sub-Tasks:
Key
Summary
Type
Status
Assignee
DOCU-126 Comment module docu should provide de... Sub-task Closed Antti Hietala  
Template:
Acceptance criteria:
Empty
Task DoR:
Empty
Date of First Response:

 Description   

In the Commenting module article:

  • Explain what kind of commenting is available with CE (IntenseDebate) and EE (Magnolia's own). What are the advantages of each approach?
  • Write procedures for setting up commenting with CE and EE. This is somewhat documented but should be improved.
  • For IntenseDebate commenting, wiki has some instructions but they are not detailed enough because users are getting lost. Include instructions how to create an IntenseDebate account and get the ID.
  • For EE commenting, explain what the roles forum-base, page-comments-user, forum-moderator-base, forum-pagecomments-moderator and forum-pagecomments-admin are used for. They ship with the standard installation but are not assigned to any users or groups out-of-the-box. Write a use case for assigning the roles to users so that anonymous users can view page comments, registered users can add comments, an editor promoted to a moderator can moderate etc.
  • Link to the commenting video.
  • Describe a clustered Magnolia configuration where user generated content such as comments are stored in a clustered repository accessed by all public instances.

Resources:



 Comments   
Comment by Ruth Stocks [ 27/Apr/11 ]

Article at http://docuauthor.magnolia-cms.com/cookbook/commenting-CE-EE.html.

I included an additional section "Adding commenting to templates".

A few issues:

  • Unless I've missed something, there seems to be a problem with the "latestComments" paragraph. I've included a screenshot of the freemarker error when trying to use the paragraph - see "Enterprise Edition - Standard Templating Kit section".
  • I can't figure out the markup for including code in a numbered list - see "Adding commenting to templates - Amend mainArea template" section.
Comment by Antti Hietala [ 19/May/11 ]

Feedback:

  • Move content to Commenting module article as requested in ticket.
  • Instead of Enterprise Edition and Community Edition as top level concepts, use Magnolia Commenting and IntenseDebate commenting. Explain in the text how they relate to editions.
  • Explain EE commenting first since that is what the module installs and what we sell.
  • "This article covers..." list is redundant since the same topics are in the TOC right below.
  • As requested in ticket, describe the advantages of Magnolia vs. IntenseDebate commenting. See "Collaboration, social" RFP document.
  • In "Enabling and disabling commenting", do 3 and 4 as nested bullets. The steps are from different editions so it doesn't really read as a numbered procedure. Also, swap EE and CE so Magnolia's own commenting comes first.
  • See recommended use of display (vb) in MSTP: appears, displays
  • "In CE, comments are managed and monitored..." replace monitored with moderated.
  • "IntenseDebate id", abbr. -> caps. Multiple occurrences.
  • "If you want to use multiple IntenseDebase accounts..." typo
  • "you can override the default id on an individual template level." This is interesting. Provide a scenario where this might be useful.
  • "To insert your id, open Templating Kit > Site Configuration...". See MSTP: open (adj, v) for recommended use of open. I prefer click or go to.
  • You don't need to use arrows/ellipses if you just want to emphasize a single node in the tree. Just select the node. The default blue background is quite clear. See the promo example.
  • Clean screenshots, nice!
  • Restructure the "Enterprise Edition" (renamed to Magnolia Commenting) section. Try something like:
    • Magnolia Commenting
      • Paragraphs
      • Dialogs
      • Security
      • Moderating
  • The "no configuration is necessary" argument is not quite true. There is some config to do to get the latestComments para working, for example. Usually it is a good thing that you can accomplish something with configuration which is faster than changing code.
  • What is the difference between comments and stkComments paragraphs? It's probably explained below but should be where user comes across the decision for the first time.
  • "In the STK, the comments paragraph is available in /mainArea/comments in the /prototype template, accessible in Templating Kit > Site Definitions /default/templates/prototype/mainArea."
    • Say "template prototype" instead of "prototype template", see "Prototype" in the ETK draft on Google Docs.
    • It is hard to follow the path when it is not given sequentially. Simplify to "Templating Kit > Site Definitions > /default/templates/prototype/mainArea/comments"
  • Freemarker error in latestComments paragraph. This is MGNLCMNT-31. To resolve, change the type property from freemarker to stk and under parameters add two new nodes divClass (no value needed) and headingLevel=h2
  • Security permissions > Superuser. Superuser probably should not participate in moderating, deleting or activating comments in any way. Such tasks would fall to a specialized editor role ("Community Manager") in a typical production setup. Also, rather than editing the superuser role, assign the superuser user the forum-pagecomments-admin which grants the same permission.
  • "Amend mainArea template". Try to summarize the task in the heading. A savvy Magnolia user only needs to skim the headings to understand what to do. "Amend" doesn't really say what needs to be done. Suggestion:
    • "Add comments paragraph to template definition"
    • "Render comments in template script"
    • "Enable commenting on web page"
  • Bulleted list restarts. This is a known issue with the wiki renderer. Try one of these workarounds:
    • Use an HTML paragraph. With HTML you can set the <li> to start at a particular number. Your paragraph heading won't be picked up by the {toc}

      macro so you may need to create a manual TOC if the page is long and has multiple paragraphs. You can mix wiki and HTML paragraphs on the same page.

    • Move the code block after the numbered steps. The reader has to jump a bit but in a short procedure this might not matter.
    • If the code block is just a one-liner, use \\\ { {code goes here on the same line as the step\}}
    • Stop the procedure so the code block is the last item.
Comment by Ruth Stocks [ 21/Jun/11 ]

Updated module page at http://docuauthor.magnolia-cms.com/modules/commenting.html.

Deleted the cookbook article and combined it with the original module page

Comment by Ruth Stocks [ 30/Dec/14 ]

documented at:

Generated at Mon Feb 12 01:06:03 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.