Merge pull request #11 from radinamatic/docs-0.9-update

0.9 Updates
learningequality · Apr 6, 2018 · 0d926bc · 0d926bc
2 parents 1cbb9fa + 9bc9a98
commit 0d926bc
Show file tree

Hide file tree

Showing 56 changed files with 241 additions and 146 deletions.
diff --git a/docs/access.rst b/docs/access.rst
@@ -99,4 +99,4 @@ To change language in which **Kolibri** user interface is displayed, follow thes
 #. Open your user menu in the upper right corner.
 #. Select the **Change language** option.
 #. Choose the desired language.
-#. Click **Select** to confirm.
+#. Click **Confirm** and Kolibri will be displayed in the selected language!
diff --git a/docs/coach.rst b/docs/coach.rst
@@ -3,39 +3,39 @@
 Coach your Learners in Kolibri
 ##############################
 
-You can track progress of the **Learner** users, create and assign **Lessons** and **Exams** to classes or learner groups from the **Coach** dashboard. The default view of the **Coach** dashboard presents the list of **Classes** with number of learners enrolled to each class.
+You can track progress of the **Learners**, create and assign **Lessons** and **Exams** to classes or learner groups from the **Coach** dashboard. The default view of the **Coach** dashboard presents the list of **Classes** with their assigned coaches, and the number of learners enrolled in each class.
 
-Select a class from the list to access the progress-tracking features and create exams.
+Click on a class to access the progress-tracking features and create lessons and exams.
 
-	.. figure:: img/coach-home.png
-	  :alt: default coach view with list of classes
+.. figure:: img/coach-home.png
+  :alt: default coach view with list of classes
 
 .. _track_progress:
 
 
 View Learner Reports
 ~~~~~~~~~~~~~~~~~~~~
 
-This is the default view when you select a class from the **Coach** dashboard. It displays the list of learners in the class and the group they are asigned to.
+Click a class on the **Coach** dashboard to display the list of enrolled learners, and the group they are assigned to (if applicable).
 
-When you click the username of a learner, you will see the list of content they accessed and when were they last active on each of the channels:
+When you click the username of a learner, you will see a list of content channels they accessed, and the last time they were active on each of them:
 
-	.. figure:: img/learner-report-content.png
-	  :alt: Learner Reports present a quick view of all the content accessed by a learner.
+.. figure:: img/learner-report-content.png
+  :alt: Learner Reports present a quick view of all the content accessed by a learner.
 
-	  Learner Reports present a quick view of all the content accessed by a learner.
+  Learner Reports present a quick view of all the content accessed by a learner.
 
+.. note::
+  In a Learner report, the username of the selected learner will be the last item in the breadcrumb navigation menu.
 
-.. tip::
-  Username of the selected learner will be the last item in the breadcrumb menu on the top.
+Navigate the topic tree of each channel to see the progress of the selected learner for the topics, subtopics and individual resources. As you navigate, you will see topics added to the breadcrumbs menu.
 
+In the image below, you can see that the learner **Abby L.** accessed and completed only one of the subtopics from the topic **Addition and Subtraction to 10**: 
 
-Navigate the topic tree of each channel to see the progress of the selected learner for the topics, subtopics and individual resources. In the image below you can see that the learner **abbyl** accessed and completed only one of the subtopics from the topic **Addition and Subtraction to 10**: 
+.. figure:: img/learner-report-topic.png
+  :alt: Learner Reports across topics for the selected content channel.
 
-	.. figure:: img/learner-report-topic.png
-	  :alt: Learner Reports across topics for the selected content channel.
-
-	  Learner Reports across topics for the selected content channel.
+  Learner Reports across topics for the selected content channel.
 
 
 .. _exercise_progress:
@@ -57,20 +57,20 @@ In the example below, the progress bar for the exercise **Subtract within 5** wi
 
 Click the exercise title to see all the answers and attempts on each question. In the figure below, you can see the progress of the learner **Hansen** for the exercise **Numbers to 120**. The exercise is still **In progress** as the learner has not completed the 5 correct answers in the row. You can also see that for the *Question 13*, the learner has given the correct answer only on the 4th attempt, which indicates that they are still struggling with the given concept.
 
-	.. figure:: img/learner-exercise-attempts.png
-	    :alt: View the details for all the answers and attempts for a single exercise.
+.. figure:: img/learner-exercise-attempts.png
+    :alt: Details for answers and attempts of a single exercise.
 
-	    View the details for all the answers and attempts for a single exercise.
+    Details for answers and attempts on a single exercise.
 
 
 How does it looks if learner A does 5 correct answers in a row on their first try, but learner B gets 10 wrong answers in a row before giving 5 correct ones in a row? In both cases, the progress would show as 100%, and you would have to click each learner's name to access their progress report and attempt history.
 
 In the figure below, you can see the progress of 5 learners for the exercise **Numbers to 120** in ascending order.
 
-	.. figure:: img/exercise-view-detail.png
-	    :alt: View the progress for a single exercise or resource in a topic.
+.. figure:: img/exercise-view-detail.png
+    :alt: View the progress for a single exercise or resource in a topic.
 
-	    View the progress for a single exercise or resource in a topic.
+    View the progress for a single exercise or resource in a topic.
 
 
 
@@ -96,15 +96,15 @@ If the class learners have access to more than one channel, you will see the lis
 
 .. _topic_view:
 
-View Class Activity by Topic
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+View Class Activity by Channels
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Use this view to access the full report of activity progress for the selected class. You can navigate channels by topics and subtopics until you see the progress of each class learner for a specific item.
 
 	.. figure:: img/topic-activity.png
 	  :alt: Use the topic view to see the average progress for exercises and resources for all the learners in the class.
 
-	  Use the topic view to see the average progress for exercises and resources for all the learners in the class.
+	  Use the channel view to see the average progress for exercises and resources for all the learners in the class.
 
 
 When you navigate to the last level in the topic tree, you can see the average progress of all class learners for each exercise or resource (video, document, HTML5 activity) in that particular topic.
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -42,7 +42,7 @@ Both Kolibri and `Kolibri Studio <https://studio.learningequality.org/>`_ are tr
 +---------------------------+-----------------+-----------------+
 | Urdu (Pakistan)           | ✓               | ⨯               |
 +---------------------------+-----------------+-----------------+
-| Hindi                     | ⨯   (✓ ver 0.4) | ⨯               |
+| Hindi                     | ✓               | ⨯               |
 +---------------------------+-----------------+-----------------+
 
 To contribute to Kolibri and Kolibri Studio as a translator, you can get started over on our `translations and internationalization page <http://learningequality.org/translate/>`_.

diff --git a/docs/img/add-content-exam.png b/docs/img/add-content-exam.png
diff --git a/docs/img/add-users-to-class.png b/docs/img/add-users-to-class.png
diff --git a/docs/img/assign-coach.png b/docs/img/assign-coach.png
diff --git a/docs/img/breadcrumbs-folded.png b/docs/img/breadcrumbs-folded.png
diff --git a/docs/img/change-exam-status.png b/docs/img/change-exam-status.png
diff --git a/docs/img/change-lesson-status.png b/docs/img/change-lesson-status.png
diff --git a/docs/img/classes.png b/docs/img/classes.png
diff --git a/docs/img/coach-home.png b/docs/img/coach-home.png
diff --git a/docs/img/coach-recent.png b/docs/img/coach-recent.png
diff --git a/docs/img/coach-type.png b/docs/img/coach-type.png
diff --git a/docs/img/confirm-add-users-to-class.png b/docs/img/confirm-add-users-to-class.png
diff --git a/docs/img/copy-exam.png b/docs/img/copy-exam.png
diff --git a/docs/img/copy-lesson.png b/docs/img/copy-lesson.png
diff --git a/docs/img/delete-account-confirm.png b/docs/img/delete-account-confirm.png
diff --git a/docs/img/exam-report-detail.png b/docs/img/exam-report-detail.png
diff --git a/docs/img/exam-report.png b/docs/img/exam-report.png
diff --git a/docs/img/exam-result.png b/docs/img/exam-result.png
diff --git a/docs/img/exam-visibility.png b/docs/img/exam-visibility.png
diff --git a/docs/img/exams-lessons.png b/docs/img/exams-lessons.png
diff --git a/docs/img/exams3.png b/docs/img/exams3.png
diff --git a/docs/img/exercise-view-detail.png b/docs/img/exercise-view-detail.png
diff --git a/docs/img/facility-setup-details.png b/docs/img/facility-setup-details.png
diff --git a/docs/img/facility-setup.png b/docs/img/facility-setup.png
diff --git a/docs/img/groups.png b/docs/img/groups.png
diff --git a/docs/img/learner-report-content.png b/docs/img/learner-report-content.png
diff --git a/docs/img/learner-report-topic.png b/docs/img/learner-report-topic.png
diff --git a/docs/img/lesson-options.png b/docs/img/lesson-options.png
diff --git a/docs/img/lessons.png b/docs/img/lessons.png
diff --git a/docs/img/manage-exams.png b/docs/img/manage-exams.png
diff --git a/docs/img/manage-facility.png b/docs/img/manage-facility.png
diff --git a/docs/img/manage-users.png b/docs/img/manage-users.png
diff --git a/docs/img/move-learners.png b/docs/img/move-learners.png
diff --git a/docs/img/move-learners2.png b/docs/img/move-learners2.png
diff --git a/docs/img/name-facility.png b/docs/img/name-facility.png
diff --git a/docs/img/new-class.png b/docs/img/new-class.png
diff --git a/docs/img/new-lesson.png b/docs/img/new-lesson.png
diff --git a/docs/img/remove-coach-from-class.png b/docs/img/remove-coach-from-class.png
diff --git a/docs/img/remove-user-from-class.png b/docs/img/remove-user-from-class.png
diff --git a/docs/img/select-language.png b/docs/img/select-language.png
diff --git a/docs/img/topic-activity.png b/docs/img/topic-activity.png
diff --git a/docs/install/_advanced.rst b/docs/install/_advanced.rst
@@ -10,7 +10,7 @@ Generic installation (pip install)
 
 Once Kolibri is released, you may install it as a standard package from PyPi using this command::
 
-    $ pip install kolibri --pre
+    pip install kolibri --pre
 
 
 .. _ppa-installation:

diff --git a/docs/install/_initial_setup.rst b/docs/install/_initial_setup.rst
@@ -34,7 +34,7 @@ To do the initial setup of after the installation, follow these steps.
 
 	   Select the username and password for the facility Super User.
 
-#. **Choose a Facility setup.** Click the **Setup details** for more information about user permissions for each setup type.
+#. **Choose a Facility setup.** Click the **More information** link for more details about user permissions for each setup type.
 
 +--------------------------------------------------+----------------------------------------------------+
 | Facility type                                    | Users                                              |

diff --git a/docs/install/_linux.rst b/docs/install/_linux.rst
@@ -21,13 +21,10 @@ Use the following commands in Terminal to add the PPA and install Kolibri:
 Install from a .deb file
 ------------------------
 
-The advantage of having a ``.deb`` file is about portability. If you need to
-install Kolibri on devices without internet access, you can copy the file from
-device to device.
+The advantages of downloading a ``.deb`` file is the portability: you can copy the file from device to device and install Kolibri without internet access.
 
-#. Go to `learningequality.org/download <https://learningequality.org/download/>`__ and download the latest version (or have it copied to your local drive).
-#. Download the Kolibri installer  (``DEB`` file).
-#. Run the command:
+#. Download the latest Kolibri `DEB installer <https://learningequality.org/r/kolibri-deb-latest>`_, or have it copied to your local drive.
+#. Run this command from the location where you downloaded the ``DEB`` file:
 
    .. code-block:: bash
 
@@ -51,5 +48,6 @@ Uninstall
 Upgrade
 -------
 
-Upgrades are automatic when you use the PPA installation method. 
-To upgrade Kolibri with a ``.deb``, follow the same steps in :ref:`lin_deb`.
+When you use the PPA installation method, upgrades to newer versions will be automatic, provided there is internet access available.
+
+To upgrade Kolibri on a Debian device without internet access, bring the updated ``.deb`` file and follow the same steps as in :ref:`lin_deb`.
diff --git a/docs/install/_osx.rst b/docs/install/_osx.rst
@@ -13,10 +13,10 @@ Install
 #. Download the `Kolibri PEX installer <https://learningequality.org/r/kolibri-pex-latest>`_.
 #. Open Terminal in the folder where ``PEX`` file is located and run the command:
 
-  .. code-block:: bash
+	.. code-block:: bash
 
-    chmod +x kolibri-installer-filename.pex
-    ./kolibri-installer-filename.pex start
+	  chmod +x kolibri-installer-filename.pex
+	  ./kolibri-installer-filename.pex start
 
 #. Once the command finishes, open the default browser at http://127.0.0.1:8080 and proceed with the :ref:`setup_initial` of your facility. 
 

diff --git a/docs/install/_system_requirements.rst b/docs/install/_system_requirements.rst
@@ -3,62 +3,76 @@
 System requirements
 ===================
 
+
 Operating systems
 -----------------
 
- - Windows Vista, 7, 8.1, 10
- - Debian/Ubuntu: 14.04, 16.04 and up - anything that's *not* end-of-life.
- - Linux: Any system with Python 2.7
- - Mac OSX 10.9, 10.10 and 10.11
- - Debian/Raspberry Pi packages: Wheezy or later
- - *(planned)* Android: 4.2.2 or later
+Servers
+^^^^^^^
+
+* Windows
+
+  - Supported: Vista, 7, 8, 10
+  - **Not supported: Windows XP** cannot be used to install Kolibri server, but could potentially work as a client device if the browsers are `as up-to-date as possible <https://support.mozilla.org/en-US/questions/1173904>`_.
+
 
+* MacOS: 10.6+ (install with :ref:`PEX <osx>`)
+* Ubuntu: 14.04, 16.04 and up - anything that's *not* end-of-life
+* Debian/Raspbian: Jessie or later
+* Linux: Any system with Python 2.7
+* **Android: not yet supported**
+* **iOS: not yet supported**
+
+Clients
+^^^^^^^
+* Windows: IE 11+, Chrome, Firefox
+* MacOS: all browsers supported
+* Linux: all browsers supported
+* Android: 4.2+ 
+* iOS: **Safari not supported**, Chrome & Firefox supported
 
-.. TODO - Limited support
 
 Supported Browsers
-------------------
+******************
 
- - IE10+, Microsoft Edge
+ - IE11+, Microsoft Edge
  - Firefox
  - Chrome
  - *(planned)* Safari
  - *(planned)* Epiphany on Raspberry Pi
  - *(planned)* others on Android and  iOS.  
 
 
-.. TODO - Known issues
-
-
 Video playback
---------------
+**************
 
-Videos are MP4 encoded, and require no aditional installation of plugins or codecs.
+Videos are MP4 encoded, and require no additional installation of plugins or codecs.
 
 
 Hardware requirements
 ---------------------
 
-.. tip:: You can download the full `Kolibri Hardware Guide <https://learningequality.org/r/hardware-guide>`_ and examples of `Hardware Configurations for Kolibri <https://learningequality.org/r/hardware>`_ as PDF documents.
+.. tip:: Below you will find general recommendations regarding hardware requirements. To read more detailed information and find out examples of hardware setups that have been implemented by our partners and users, download the full `Kolibri Hardware Guide <https://learningequality.org/r/hardware-guide>`_ and examples of `Hardware Configurations for Kolibri <https://learningequality.org/r/hardware>`_ (PDF documents).
 
-Clients
+Servers
 ^^^^^^^
 
-Very old desktops and very low-power computers can be used as client devices to access Kolibri. For instance, some deployments are known to use first-gen Raspberry Pi as desktop computers.
+Minimum hardware requirements to run Kolibri as a server:
 
-It is always a good idea to do a practical test, but when you want to deploy Kolibri, usually it's not necessary to scale your hardware. The main concern is that your system needs a video card and driver that can play the videos.
+ - 500 MB RAM (1 GB recommended)
+ - 500 MHz CPU (1 GHz recommended)
+ - Hard drive space depends on the size of the content channels you intend to import from `Kolibri Studio <https://studio.learningequality.org/>`_ or a local storage device.
 
-Servers
-^^^^^^^
+If you have a facility with less than 30 computers, a device as simple as a `Raspberry Pi <https://www.raspberrypi.org/>`_ is known to work fine as a server.
+
+.. TODO - REVIEW with RPi package reqs if necessary
 
-Kolibri hardware requirements as a server are next to nothing.
+   .. note:: In case you are deploying on Linux and want an efficient setup, use the ``kolibri-raspberry-pi`` package, it doesn't require a specific architecture, but it's required to use if you deploy on a system with specs equivalent to or smaller than Raspberry Pi.
 
- - 256 MB
- - 500 MHz CPU
- - Hard drive space depends on the size of the content channels you intend to import into Kolibri
 
-If you have a center with less than 30 computers, a device as simple as a Raspberry Pi is known to work fine as a server.
+Clients
+^^^^^^^
 
-.. TODO - REVIEW with RPi package reqs if necessary
+Very old desktops and very low-power computers can be used as client devices to access Kolibri. For instance, some deployments are known to use first-gen Raspberry Pi as desktop computers.
 
-   .. note:: In case you are deploying on Linux and want an efficient setup, use the ``kolibri-raspberry-pi`` package, it doesn't require a specific architecture, but it's required to use if you deploy on a system with specs equivalent to or smaller than Raspberry Pi.
+It is always a good idea to do a practical test, but when you want to deploy Kolibri, usually it's not necessary to scale your hardware. The main concern is that your system needs a video card and driver that can play the videos.
diff --git a/docs/learn.rst b/docs/learn.rst
@@ -87,18 +87,19 @@ In the **Recommended** tab you can see various sections:
 * **Resume** displays activities that you started but haven’t finished yet.
 * **Featured in...** displays a preview of activities for each content channel you have access on Kolibri.
 
+These learning topics and materials are either related to what you were doing the last time you used Kolibri. or recommended by your teachers and coaches.
+
 .. note::
    **Next steps** and **Resume** are not visible if you are browsing as a guest.
 
-The number of displayed content items in each row will depend on the width of your display, but you can browse through with the |arrow-left| and |arrow-right| icons at the beginning and the end of the section rows.
+The number of displayed content items in each row will depend on the width of your display, and you can browse with the |arrow-left| and |arrow-right| icons at the beginning and the end of the section rows.
 
 	.. figure:: img/learn.png
 		:alt: Learn page gives you access to all Kolibri learning content and activities.
 
 		Learn page gives you access to all Kolibri learning content and activities.
 
 
-
 Navigate Kolibri topics with breadcrumb links
 """""""""""""""""""""""""""""""""""""""""""""
 
@@ -109,6 +110,10 @@ When you are browsing a topic in Kolibri, the **Breadcrumb** links indicate prev
 
 	Use breadcrumbs links to navigate back through Kolibri topics.
 
+If the full length of the breadcrumbs becomes too wide for the width of your display, the more general topics will be hidden. Click the leftmost down arrow icon to access them.
+
+.. figure:: img/breadcrumbs-folded.png
+	:alt: click the expand more button to reveal folded breadcrumb links
 
 Search
 ^^^^^^
@@ -183,7 +188,6 @@ To play videos and listen to audio files in Kolibri you have several available c
 Use the **Download content** button below the player to download the video, audio and thumbnail files to your computer. Some videos will provide multiple resolution options.
 
 
-
 PDF Viewer options
 """"""""""""""""""
 
@@ -212,9 +216,6 @@ Click on a lesson title to open its content, and follow the indications of your
 	:alt: lessons tab
 
 
-Here you will find learning topics and materials related to what you were doing the last time you used Kolibri, or those recommended by your teachers and coaches (not visible if you are browsing as a guest).
-
-
 .. _exams:
 
 Exams
@@ -225,8 +226,9 @@ If your teacher or coach scheduled an exam for you or your class, it will be ava
 .. figure:: img/exams3.png
 	:alt: exams tab
 
+If the exam is listed as *Not started*, follow these steps.
 
-#. Press the button **Start** when you are ready to start taking exam.
+#. Click on the exam when you are ready to start taking it.
 #. You can go on answering the questions in the order you prefer: move through questions with **Previous** and **Next question** buttons, or click on the question number in the column on the left side.
 
 	.. figure:: img/exam-detail.png
@@ -235,13 +237,14 @@ If your teacher or coach scheduled an exam for you or your class, it will be ava
 #. Each time you fill in the answer field, or select one of the available options, the question will be marked by a colored dot in the column on the left side.
 #. You can review and correct your answers to all questions as many times you need before submitting.
 #. Press the *Back to exam list* if you want to pause the exam and come back later.
-#. Press the button **Continue** to resume when you are ready.
+#. Press the button **Submit exam** when you want to submit it for grading.
 
-	.. figure:: img/exam-continue.png
-		:alt: exams tab
+If the exam in the **Class** tab is listed as having *...questions left*, click on it to resume when you are ready.
 
-#. Press the button **Submit exam** when you are positive that you answered all the questions, and you want to submit it for grading.
-#. You will see instant feedback with the result of your exam.
+Once you submit the exam, it will be listed as *Completed* in the **Class** tab, but you can click on it to see the score and review your answers.
 
 .. figure:: img/exam-result.png
 	:alt: exams tab
+
+.. tip::
+   Use the **Show correct answer** checkbox to visualize the answer for the questions that you did not answer correctly.