Merge pull request #470 from ox-it/revised-docs-from-sprint

Revised docs from sprint

docs/source/conf.py

@@ -50,6 +50,7 @@
 
 rst_epilog = """
 .. |upcoming| replace:: New Feature!
+.. |changes| replace:: There have been changes to this part of Oxford Talks in the latest release (May 2016)
 """
 
 

docs/source/http_api/endpoints/collections.rst

@@ -1,15 +1,15 @@
-**********************
-Retrieve List via ID
-**********************
+**************************
+Retrieve Collection via ID
+**************************
 
-Endpoint to retrieve information about all talks collected together in a Public List
+Endpoint to retrieve information about all talks collected together in a Public Collection
 
 All the responses conform to the `HAL specification <http://stateless.co/hal_specification.html>`_.
 
 
 .. http:get:: /collections/id/(string:id)
 
-    Retrieve list by unique slug identifier, including all talks
+    Retrieve collection by unique slug identifier, including all talks
 
     **Example request**:
 
@@ -66,16 +66,16 @@ All the responses conform to the `HAL specification <http://stateless.co/hal_spe
 
     The response can be either in XML or JSON dependent on the 'accept' header in the request.
 
-    :statuscode 200: List found
-    :statuscode 404: List not found
+    :statuscode 200: Collection found
+    :statuscode 404: Collection not found
     :statuscode 503: Service not available
 
 
 
 Parameters Reference
 ====================
 
-id : list slug as string
+id : collection slug as string
       * Format :code:`f8ecded3-d2af-4585-bd3b-5cd7440795b9`
 
 from : date string (`'yyyy-mm-dd'`), optional
@@ -85,4 +85,5 @@ from : date string (`'yyyy-mm-dd'`), optional
 to : date string (`'yyyy-mm-dd'`), optional
     * End date for the list of talks.
     * Format :code:`yyyy-mm-dd`
-    * Note that the end time is currently assumed to be 00:00 not 23:59 (see `#394 <https://github.com/ox-it/talks.ox/issues/394>`_ for progress on this issue)
+    * Or use :code:`plus[n]` for the next [n] days (e.g.: plus7)
+    * Note that the issue with the end time (assumed to be 00:00 not 23:59) has now been resolved

docs/source/http_api/endpoints/search.rst

@@ -97,7 +97,8 @@ from : date string (`'yyyy-mm-dd'`), **required**
 to : date string (`'yyyy-mm-dd'`), optional
     * End date for the list of talks.
     * Format :code:`yyyy-mm-dd` or :code:`dd/mm/yy` (deprecated)
-    * Note that the end time is currently assumed to be 00:00 not 23:59 (see `#394 <https://github.com/ox-it/talks.ox/issues/394>`_ for progress on this issue)
+    * Or use :code:`plus[n]` for the next [n] days (e.g.: plus7)
+    * Note that the issue with the end time (assumed to be 00:00 not 23:59) has now been resolved
 
 subdepartments : boolean, optional
     * If true, include all sub-organisations of the specified department within the search (see organising_department below)

docs/source/http_api/endpoints/series.rst

@@ -77,12 +77,28 @@ All the responses conform to the `HAL specification <http://stateless.co/hal_spe
                 }]
             }
         }
-
-    :param id: The unique slug identifier for the series
-    :type id: string
-
+
     The response can be either in XML or JSON dependent on the 'accept' header in the request.
 
     :statuscode 200: Series found
     :statuscode 404: Series not found
     :statuscode 503: Service not available
+
+
+Parameters Reference
+====================
+
+id : series slug as string
+  * Format :code:`f8ecded3-d2af-4585-bd3b-5cd7440795b9`
+
+from : date string (`'yyyy-mm-dd'`), optional
+     * Start date for the list of talks.
+     * Format as :code:`yyyy-mm-dd`
+
+to : date string (`'yyyy-mm-dd'`), optional
+    * End date for the list of talks.
+    * Format :code:`yyyy-mm-dd`
+    * Or use :code:`plus[n]` for the next [n] days (e.g.: plus7)
+    * Note that the issue with the end time (assumed to be 00:00 not 23:59) has now been resolved
+
+

docs/source/index.rst

@@ -7,17 +7,17 @@
 Oxford Talks
 ############
 
-.. Note:: Some new features have just been released!
+.. Note:: Some small changes have been made in the latest release of the software!
 
 .. toctree::
    :maxdepth: 1
    :caption: User Guide
 
-   Explore Oxford Talks (new) <user/talk-users/explore-talks>
-   Collect talks you are interested in (new) <user/talk-users/make-a-list>
-   Copy talks to your own calendar (new) <user/talk-users/add-to-your-calendar>
-   Get an up-to-date feed in your calendar (new) <user/talk-users/feed-in-your-calendar>
-   Set up email reminders (new) <user/talk-users/email-reminders>
+   Explore Oxford Talks <user/talk-users/explore-talks>
+   Collect talks you are interested in <user/talk-users/make-a-list>
+   Copy talks to your own calendar <user/talk-users/add-to-your-calendar>
+   Get an up-to-date feed in your calendar <user/talk-users/feed-in-your-calendar>
+   Set up email reminders <user/talk-users/email-reminders>
 
 .. toctree::
     :maxdepth: 1
@@ -27,7 +27,8 @@ Oxford Talks
     user/general/log-in
     user/general/terms
     user/general/organisers
-    user/general/differences
+    user/general/release-notes-2016-5
+    user/general/old-talks
 
 .. toctree::
     :maxdepth: 1
@@ -43,6 +44,7 @@ Oxford Talks
     user/talk-editors/last-minute-changes
     user/talk-editors/share-editing
     user/talk-editors/people-details
+    user/talk-editors/identifying-topic
 
 
 

docs/source/user/general/log-in.rst

@@ -1,3 +1,6 @@
+
+
+
 Logging in and out
 ==================
 
@@ -8,7 +11,7 @@ Log in
 
 .. image:: images/log-in/log-in.png
    :alt: Log in
-   :height: 101px
+   :height: 114px
    :width: 614px
    :align: center
 
@@ -18,21 +21,24 @@ Log in
 * Once you have signed in, clicking the **Continue to** button will take you back to Oxford Talks
 
 .. image:: images/log-in/d1a11eac-3994-43ab-a04e-def878f18588.png
-   :alt:
+   :alt: 
    :height: 389px
    :width: 614px
    :align: center
 
+
+.. Note:: Just occasionally there are problems logging in with Internet Explorer. If you encounter this, close down your browser to log yourself out of everything, then open your browser again and try logging in to Oxford Talks.
+
 Log out
 -------
 
 .. image:: images/log-in/log-out.png
    :alt: Log out
-   :height: 81px
-   :width: 614px
+   :height: 167px
+   :width: 370px
    :align: center
 
 
-The **Logout** button is also located at the far right of the toolbar at the top of the screen.
+The **Logout** link is also located in the drop down list underneath your name at the top of the screen.
 
-.. Note::  Clicking this will only log you out of the Oxford Talks website. You will still be logged in to any other web pages you have logged in to with your Single Sign On username and password using the WebAuth page. If you really want to sign out of everything, then close down your browser.
+.. Note::  Clicking this will only log you out of the Oxford Talks website. You will still be logged in to any other web pages you have logged in to with your Single Sign On username and password using the WebAuth page. If you really want to sign out of everything, then close down your browser.

docs/source/user/general/old-talks.rst

@@ -0,0 +1,24 @@
+Archiving old Talks
+===================
+
+The old Oxford Talks system is about to be closed down. Talks entered on that system **before February 2015** will be deleted.
+
+If you would like to get a copy of your old talks:
+
+1. Go to http://old.talks.ox.ac.uk/index
+
+2. Find your list and note down its ID number
+
+3. Type the following into the address bar of your browser substituting your list ID number for [ID number]
+
+:: 
+
+     http://old.talks.ox.ac.uk/show/xml/[ID number]?start_time=0
+
+or, for a table (but not quite so much information)
+
+::
+
+     http://old.talks.ox.ac.uk/show/table/[ID number]?layout=empty&start_time=0
+
+4. You can copy and paste the information on the resulting web page into Notepad or a similar plain text app.

docs/source/user/general/release-notes-2016-5.rst

@@ -0,0 +1,93 @@
+
+
+
+Latest Changes - May 2016
+=========================
+
+We've just released a new version of the Oxford Talks software. Here are the main changes.
+
+Look and Feel
+-------------
+
+We've tidied up the look of the site to make it easier to find out what's coming up:
+
+#. The home page has been redesigned - it should be quick to find what's going on this week and next by using the tabs across the top. 
+#. You *might* miss the personal listing - **My Talks** - at the bottom of the old home page. This is now on the drop down list under your username.
+#. The talks should be easier to scan for interesting titles or speakers. Important information about the talk should be easily noticeable as well.
+#. You can now browse departments and topics.
+
+.. image:: images/release-notes-2016-5/look-and-feel.png
+   :alt: Look and Feel
+   :height: 435px
+   :width: 614px
+   :align: center
+
+
+Lists
+-----
+
+Lists have been renamed **Collections** as we thought that this better reflected the way they work. It is just a name change - everything works in the same way as before.
+
+You can now add a department to a collection. Good news if you want to create a collection of all the series in your department and also talks of interest from elsewhere on Oxford Talks.
+
+.. image:: images/release-notes-2016-5/lists.png
+   :alt: Lists
+   :height: 237px
+   :width: 614px
+   :align: center
+
+
+Date Picker
+-----------
+
+We've got a nicer date picker now for setting start and end dates. It is much easier to use.
+
+.. image:: images/release-notes-2016-5/date-picker.png
+   :alt: Date Picker
+   :height: 329px
+   :width: 614px
+   :align: center
+
+
+Speakers and Audience
+---------------------
+
+#. Speakers should now appear in the order you've added them. It was going to be tricky to allow you to drag and drop speakers to get them into the right order, so if you add them in the wrong order then you'll have to remove them and add them again.
+#. If you have too many speakers to list, we've allowed you to tick a box to indicate *Various Speakers*. 
+#. There's now a text box you can use to specify the type of audience, if *public* or *university only* are not sufficient.
+
+.. image:: images/release-notes-2016-5/speakers-and-audience.png
+   :alt: Speakers and Audience
+   :height: 179px
+   :width: 451px
+   :align: center
+
+
+Talks in Preparation
+--------------------
+
+We've clarified talks 'in preparation'. Now a talk is automatically published when you create it, but you can switch it to 'in preparation' to let your attendees know that some details may change.
+
+A key thing to note is that in preparation talks appear in ALL listings and are clearly flagged as 'in preparation'.
+
+Cancelled Talks
+---------------
+
+You can now also flag a talk as cancelled. 
+
+.. image:: images/release-notes-2016-5/cancelled-talks.png
+   :alt: Cancelled Talks
+   :height: 362px
+   :width: 559px
+   :align: center
+
+
+Developers
+----------
+
+There are one or two extras in the API now.
+
+#. An important point - talks 'in preparation' (see above) are listed in the API output and are indicated as such with the **Status** field. 
+#. The from and to parameters work properly and there is also a time delta option e.g. (from=today&to=plus7) 
+#. As you can now add a department to a collection (see above), this should simplify requests.
+#. We've added hosts, timezone information and .ics links to the output.

docs/source/user/general/terms.rst

@@ -1,5 +1,3 @@
-.. Note:: |upcoming|
-
 Glossary of Terms used by Oxford Talks
 ======================================
 
@@ -8,20 +6,26 @@ Series
 
 A Series is where a talk 'belongs' when you create it - for instance it may be part of a seminar series or a conference. We recommend that you only enter details about talks you organize yourself, like your Departmental Friday Seminars, or your Club meetings. You have to  :doc:`be a Talks Editor <../talk-editors/sign-up>` to be able to create a Series.
 
-List
-----
+Collection (List)
+-----------------
+
+A Collection comprises talks owned and organized by other people, already added to Oxford Talks, and usually belonging to a variety of different series. For example, a collection of 'Talks about Science and Art' could include talks from the Department of Chemistry and the Department of History. 
+
+Note that it might not always be necessary to make a manual collection - talks can be assigned to the two categories below (Organising Department and Topic) allowing us to create automatic listings. You can also add an entire series or a department to a collection, if you do this then all talks belonging to that series or department will appear in the collection automatically. 
+
+Anyone with a University Single Sign On username and password can compile a Collection. 
 
-A List is a collection of talks owned and organized by other people, already added to Oxford Talks, and usually belonging to a variety of different series. For example, a list of 'Talks about Science and Art' could include talks from the Department of Chemistry and the Department of History. Note that, although it is possible to collect talks into a List, it might not always be necessary to do this manually - talks can be assigned to the two categories below (Organizing Department and Topic) allowing us to create automatic listings. Anyone with a University Single Sign On username and password can compile a List.
+In an earlier version of the software Collections were called Lists.
 
-Organizing Department
+Organising Department
 ---------------------
 
 Many talks and series of talks are organized by a University department or unit. When a talk is added, it can be tagged with the department (or sub-unit within that department). This makes it simple to pull out all a department's (or even a Division's) talks.
 
 Topic
 -----
 
-Although talks may be organized by a single department, they are often relevant to students and researchers in other departments right across the University. Tagging by Topic means that lists of talks on various subject areas can be pulled out automatically. We have used the Library of Congress Subject Headings for our topic choices, which means that the options for potential listings by topic are quite substantial - but if none of the available topics quite fits the bill, there is always the option to create a List.
+Although talks may be organized by a single department, they are often relevant to students and researchers in other departments right across the University. Tagging by Topic means that lists of talks on various subject areas can be pulled out automatically. We have used the Library of Congress Subject Headings for our topic choices, which means that the options for potential listings by topic are quite substantial - but if none of the available topics quite fits the bill, there is always the option to create a Collection.
 
 Talks Organiser
 ---------------