<sect1 id="requirements" xreflabel="Requirements Document">
  <title>Requirements Document</title>

  <sect2 id="requirements-introduction" xreflabel="Introduction">
    <title>Introduction</title>

    <para>This is the requirements document for the General Comments
      package for ACS 4.0. General Comments is an application that takes
      advantage of the ACS Messaging service package.</para>
  </sect2>

  <sect2 id="requirements-vision-statement" xreflabel="Vision Statement">
    <title>Vision Statement</title>

    <para>User feedback and engagement is the very heart of a
      collaborative community. General Comments allows users to comment
      on any object in the community, such as articles, white papers,
      press releases or pictures.</para>

    <para>Comments are not limited to text, but can include attachments
      such as links, pictures or other documents.</para>

    <para>Users can edit their own comments and an administrator can
      choose to moderate all or particular comments before they go live
      on the site.</para>
  </sect2>

  <sect2 id="requirements-application-overview" xreflabel="Application Overview">
    <title>Application Overview</title>

    <para>General Comments is an application package that relies on the
      ACS Messaging package. Comments can be associated with any object
      in ACS 4.0, which gives you the benefits of the Permission System.
      Comments are stored as ACS Messages.</para>

    <para>When a user creates a comment, General Comments stores the
      comment as an ACS Message and associates the comment to the object
      commented on. The value set by the adminstrator on whether comments
      go live immediately or needs approval first is stored along with
      the comment during this phase. After this, the user is presented
      with a page that displays contents of the comment along with
      revision history, attachments, and links to perform actions on the
      comment such as adding attachments or editing the comment.</para>
  </sect2>

  <sect2 id="requirements-use-cases-and-user-scenarios" xreflabel="Use-cases and User-scenarios">
    <title>Use-cases and User-scenarios</title>

    <para>This package supports empowering all users with the option of
      adding comments to objects in the system, and editing their own
      comments later on.</para>

    <para><phrase>A user adding a comment:</phrase></para>
    <para>Nurse Nancy is browsing through an ACS 4.0 site that has a page for
      medical emergencies. Upon reaching the bottom of the page, Nancy
      sees a posting that reads, "<emphasis>Please help, my child has just
      swallowed some cleaning solution!!!</emphasis>". Nancy sees that this
      posting was made only 30 seconds ago and quickly posts a remedy for
      this situation. After she makes her posting, she immediately
      revisits the page and happily sees that her posting is already
      available.</para>

    <para><phrase>A user editing an old comment:</phrase></para>
    <para>George Genius is reviewing all of the comments he has posted over
      the last 24 hours. In one of his postings, George notices that his
      mathematical formula for earthquake prediction was incorrect. He
      then clicks on the edit link, makes changes to his formula and
      submits his changes. Since comments are moderated, others will only
      see his older incorrect version until his changes are approved.
      George eagerly awaits for his changes to be approved so that he
      won't be ridiculed by his colleagues for his mistakes.</para>

    <para><phrase>An adminstrator moderating:</phrase></para>
    <para>Adam Admin is looking over all recently unnapproved changes to
      comments. Adam sees that George Genius has made a correction to the
      earthquake prediction formula in which he helped write. He believes
      that the their original formaula is correct, so Adam does not
      approve of the changes. Several days later, George barges into
      Adam's office wondering why his changes were not approved. After a
      few hours George convinces Adam that the new modifications were
      correct, and so Adam approves George's comment.
    </para>
  </sect2>

  <sect2 id="requirements-related-links" xreflabel="Related Links">
    <title>Related Links</title>

    <itemizedlist>
      <listitem><para><xref linkend="design"></xref></para></listitem>
      <listitem><para><ulink url="/doc/acs-messaging/">ACS Messaging</ulink></para></listitem>
    </itemizedlist>
  </sect2>

  <sect2 id="requirements-requirements-data-model" xreflabel="Requirements: Data Model">
    <title>Requirements: Data Model</title>

    <para><phrase>10.0</phrase> Comments can be attached to any object in the system.</para>

    <para><phrase>10.10</phrase> Maintain revisioning of comments.</para>

    <para><phrase>10.20</phrase> Store comment as an acs-message.</para>

    <para><phrase>10.30</phrase> Allow separation of comments on an object.</para>

    <para><phrase>10.40</phrase> Allow file and url attachments to comments.</para>

    <para><phrase>10.50</phrase> Allow limitations on size of file attachments.</para>

    <para><phrase>10.60</phrase> Use permissioning system to control creation of comments.</para>
  </sect2>

  <sect2 id="requirements-requirements-api" xreflabel="Requirements: API">
    <title>Requirements: API</title>

    <para><phrase>20.0</phrase> A summary type function that retrieves all
      comments for a particular object.</para>

    <para><phrase>20.10</phrase> A link function that generates an
      appropriate link to add a comment.</para>
  </sect2>

  <sect2 id="requirements-requirements-interface" xreflabel="Requirements: Interface">
    <title>Requirements: Interface</title>

    <para><phrase>The Community Member's Interface</phrase></para>
    <para>The user interface for community members is a set of HTML pages
      that allow creation and editing of comments.</para>

    <para><phrase>30.0</phrase> Customized presentation.</para>

    <para><phrase>30.0.10</phrase> Show all comments that the user created.</para>

    <para><phrase>30.0.20</phrase> Have sliders to show approved/uapproved comments.</para>

    <para><phrase>30.0.30</phrase> Have sliders to show comments by age.</para>

    <para><phrase>30.10</phrase> Comments can be viewed in detail.</para>

    <para><phrase>30.20</phrase> Provide ways for a user to add attachments to a comment.</para>

    <para><phrase>30.30</phrase> Allow editing of comments.</para>

    <para><phrase>30.40</phrase> Provide a way to display attached images.</para>

    <para><phrase>30.50</phrase> Allow download of attached files.</para>

    <para><phrase>The Administrator's Interface</phrase></para>
    <para>The user interface for adminstrative members is a set of HTML pages
      that allows deletion and approval of comments.</para>

    <para><phrase>40.0</phrase> Customized presentation.</para>

    <para><phrase>40.0.10</phrase> Show all created comments.</para>

    <para><phrase>40.0.20</phrase> Have sliders to show approved/unapproved comments.</para>

    <para><phrase>40.0.30</phrase> Have sliders to show comments by age.</para>

    <para><phrase>40.10</phrase> Allow deletion of comments.</para>
  </sect2>

  <sect2 id="requirements-revision-history" xreflabel="Revision History">
    <title>Revision History</title>

    <informaltable><tgroup cols="4"><tbody>
	  <row>
	    <entry align="center"><emphasis>
		Document Revision #</emphasis></entry>
	    <entry align="center"><emphasis>
		Action Taken, Notes</emphasis></entry>
	    <entry align="center"><emphasis>When?</emphasis></entry>
	    <entry align="center"><emphasis>By Whom?</emphasis></entry>
	  </row>

	  <row>
	    <entry>0.2</entry>
	    <entry>Revision</entry>
	    <entry>12/11/2000</entry>
	    <entry>Phong Nguyen</entry>
	  </row>

	  <row>
	    <entry>0.1</entry>
	    <entry>Creation</entry>
	    <entry>10/26/2000</entry>
	    <entry>Phong Nguyen</entry>
	  </row>
	</tbody></tgroup></informaltable>

    <para>Last modified: $Id: requirements.xml,v 1.1.1.1 2001/04/20 20:51:11 donb Exp $
    </para>
  </sect2>
</sect1>
