Merge pull request sakaiproject#2244 from nicholaswilson100/SAK-30836

SAK-30836: update README

feedback/README.md

@@ -4,11 +4,38 @@ Sakai Feeback Tool
 Overview
 --------
 
-This tool allows a Sakai user to report problems with a site's content or
-functionality. Reports are sent as emails to the problem site's contact email,
-or, if that hasn't been specified, to a user selected site maintainer. In
-addition to the two reports, there is a link to an area where you can suggest
-new features. This link has to be configured from sakai.properties.
+The Contact Us tool was developed as a way to try to direct user queries to the appropriate team or a relevant web site.
+
+The central admin team were getting fed up with receiving emails from students complaining about site content,
+eg, broken links to websites, spelling mistakes in PDFs, ambiguous questions in a test and so on.
+
+These questions need directing to the site owner or teacher of the course
+(or to anybody with site update permission unless they have hidden themselves via Preferences in My Workspace).
+
+The contact us has 4 boxes each covering a different aspect:
+
+1/ "Problem with content?"
+
+2/ "How do I do this?"
+
+3/ "I've hit a bug / technical issue"
+
+4/ "Feature suggestion"
+
+Each "box" is assigned an email address or URL and each box can be disabled in the properties file,
+so if you don't want users to suggest new features, you can remove the box.
+
+This 5 minute video may explain more: http://screencast.com/t/ctJKW7iFI
+
+The contact us tool can send an email to the helpdesk with all the relevant info automatically included
+(eg, site URL, username, browser and version, plugins installed): http://blogs.it.ox.ac.uk/adamweblearn/2016/04/the-contact-us-tool/
+
+Deployment
+----------------
+
+At Oxford, the Contact Us tool is added to every site in much the same way as the Help tool
+- it is placed just above the help tool. It is intended to replicate the "Contact Us" facility you may see on Google or other websites.
+
 
 Installation and Configuration
 ------------------------------
@@ -29,22 +56,36 @@ local.properties.
 If you have configured Recaptcha in your Sakai, Feedback will use it to
 validate unauthenticated technical feedback reports.
 
-Forcing the Tool into Sites
+
+Forcing the Tool onto Existing Sites
+---------------------------
+
+To backfill existing sites to have the Feedback Tool. you need to run a quartz
+job to add the tool to all the sites. There is a Job called "Backfill tool into sites"
+which when run can add a specific tool to all sites that match a partiular type.
+
+
+Forcing the Tool to Stay on Sites
 ---------------------------
 
-You can force all your sites to have a copy of this tool wit the following lines
+You can force all your sites to have a copy of this tool with the following lines
 in your sakai.properties
 
     # Make sure the feedback tool can't be removed from sites.
     poh.uneditables=sakai.feedback
     poh.unhideables=sakai.feedback
 
-then place a toolOrder.xml in your sakai home folder that marks the feedback tool
-as required. An example toolOrder.xml is in the root of the feedback project.
 
-To backfill existing sites to have the Feedback Tool. you need to run a quartz 
-job to add the tool to all the sites. There is a Job called "Backfill tool into sites"
-which when run can add a specific tool to all sites that match a partiular type.
+Turning Off Automatically Including the Tool in New Sites
+---------------------------------------------------------
+
+The way the Contact Us tool works by default is that, when you are creating a new
+ site, when you get to the 'Project Site Tools' page where you can choose the tools
+ to include on the new site, the Contact Us tool is automatically ticked and greyed out
+  (like the Site Info tool).  To turn off this feature so that the tool is not ticked
+  or greyed out by default, you need to remove the words "required=true"
+  in 2 places from the 'toolOrder.xml' file in the kernel module.
+
 
 Developers
 ----------