[IMP] surveys: improves all Surveys documentation

(2485389)

content/applications/marketing/survey.rst

@@ -1,8 +1,263 @@
-======
-Survey
-======
+=======
+Surveys
+=======
 
-.. toctree::
-   :titlesonly:
+**Odoo Surveys** helps users create surveys, appraisals, quizzes, and questionnaires to gather
+valuable information from their customers or employees.
 
-   survey/overview
+.. seealso::
+   - `Odoo Surveys: product page <https://www.odoo.com/app/surveys>`_
+   - `Odoo Tutorials: Surveys <https://www.odoo.com/slides/surveys-62>`_
+
+Question configuration
+======================
+
+Add a question
+--------------
+
+When you click *Add a question* in the *Questions* tab on the survey template page, a pop-up
+appears, in which you create your question.
+
+After writing your question in the *Question* field, select a *Question Type.* A preview of the
+question type is displayed on the right side of the pop-up window.
+
+.. image:: survey/preview-question-type.png
+   :align: center
+   :alt: Selecting a question type in Odoo Surveys
+
+.. _survey/question-types:
+
+Question types
+--------------
+
+The following is a list of the available *Question Types*:
+
+* **Multiple Lines Text Box** - open-text field suitable for long answers where any type of text
+  is allowed
+
+* **Single Line Text Box** - open-text field suitable for short answers where any type of text is
+  allowed
+
+* **Numerical Value** - open-text field that only accepts a number as an answer
+
+* **Date** - date selection on a calendar
+
+* **Datetime** - date and time selection on a calendar
+
+* **Multiple choice: only one answer** - closed question where only one answer can be selected
+
+* **Multiple choice: multiple answers allowed** - closed question where multiple answers can be
+  selected
+
+* **Matrix** - table of multiple choice questions that share the same possible answers
+
+Answers and Options tab
+-----------------------
+
+Features change in the *Answers* and *Options* tab. It all depends on the *Question Type*. Below are
+presented options that are common to several *Question Types*, such as *Validate entry*, *Mandatory
+Answer*, *Question Time Limit* (for *Live Sessions*), and *Conditional Display*.
+
+.. _survey/validate-entry:
+
+Validate entry
+~~~~~~~~~~~~~~
+
+Entry validation lets you define requirements for single line text length, dates, and numerical
+values. To do so, go to the *Answers* tab, tick *Validate entry*, and set a *Minimum* and a
+*Maximum* value.
+
+You can also customize the *Validation Error message* that appears beneath the field on the survey
+if an invalid answer is entered.
+
+.. note::
+   Available for: *Single Line Text Box*, *Numerical Value*, *Date*, and *Datetime*
+
+.. _survey/conditional-display:
+
+Conditional Display
+~~~~~~~~~~~~~~~~~~~
+
+*Conditional Display* means a question is only displayed if the specified conditional answer has
+been selected in a previous question.
+
+To use that feature, go to a question's *Options* tab, activate *Conditional Display*, choose a
+*Triggering Question* and select the *Triggering Answer* linked to that question. Remember,
+*Triggering Questions* can only be multiple choice.
+
+.. image:: survey/conditional-triggering-answers.png
+   :align: center
+   :alt: Conditional triggering answer fields
+
+.. tip::
+   Save the entire survey first before selecting a triggering question to update the selection of
+   triggering questions.
+
+.. note::
+   Available for **all** *Question Types*
+
+.. _survey/question-time-limit:
+
+Question Time Limit (for *Live Sessions*)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Timed questions are only available during :ref:`survey/live-session` surveys.
+
+To put a time limit on a question, open a question's *Options* tab, tick *Question Time Limit*, and
+specify a limit in seconds.
+
+.. image:: survey/question-time-limit.png
+   :align: center
+   :alt: Survey Question Time Limit
+
+.. note::
+   Available for **all** *Question Types*
+
+Survey options
+==============
+
+Questions
+---------
+
+This section primarily focuses on the overall presentation and layout of your survey. There are
+also options featuring timed and randomized surveys.
+
+First, you select the layout. You can choose from:
+
+* *One page with all the questions*
+* *One page per section*
+* *One page per question*
+
+You can also choose how you want to display the participant's progress during the survey. It can
+either be shown as a *Percentage* or a *Number* (i.e. 1 of 20 answered).
+
+Below that, you can decide if you'd like to present your participants with a *Back Button* during
+the survey. You can also decide to modify the question selection to include all answers or have
+them randomized by section. You can even add a time limit, as well.
+
+.. image:: survey/questions-setting-section.png
+   :align: center
+   :alt: Questions section of survey settings
+
+.. _survey/timed-surveys:
+
+Timed surveys
+~~~~~~~~~~~~~
+
+With timed surveys, participants must complete the survey within a predetermined amount of time.
+You can apply the same time limit feature to individual questions, as well.
+
+Timed surveys and questions ensure that all participants get the same amount of time to answer and
+complete the survey. They also discourage participants from looking up answers with external
+sources.
+
+To set a time limit on a survey, select *Survey Time Limit* under the *Options* tab of your
+survey, and enter the desired time limit (in minutes).
+
+.. image:: survey/options-tab-time-limit.png
+   :align: center
+   :alt: View of a survey form emphasizing the time limit feature in Odoo Surveys
+
+Before participants begin, they see how much allotted time they have to complete the survey. During
+the survey, a timer is shown on the pages so the user can keep track of the remaining time.
+
+.. image:: survey/time-limit-survey-clock.png
+   :align: center
+   :alt: Survey time limit clock display front-end
+
+.. important::
+   Surveys that are not submitted in time **do not** have their answers saved.
+
+.. _survey/randomized-surveys:
+
+Randomized surveys
+~~~~~~~~~~~~~~~~~~
+
+When a survey is randomized, the questions are shuffled in a random order every time a participant
+opens the survey. Random surveys are a great way to eliminate the possibility of participants
+copying off one another.
+
+Once you've enabled that feature, go to the *Questions* tab of the survey, where a *Random questions
+count* column is now present.
+
+Here you can decide how many of the questions should be taken into account during the shuffling, by
+simply selecting the number and changing it. That number corresponds to how many questions in that
+section should be randomly selected.
+
+.. image:: survey/random-questions-count.png
+   :align: center
+   :alt: Survey random questions count
+
+.. _survey/scoring:
+
+Scoring
+-------
+
+Surveys are a great way to measure a person's performance, knowledge of a subject, or overall
+satisfaction.
+
+Odoo allows you to attach points to certain answers of survey questions. These points are then
+summed up to give your participant a final score.
+
+You can choose between: *Scoring with answers at the end* **or** *Scoring without answers at the
+end*.
+
+You can set the *Success %* here, as well. The *Success %* is the percentage the user needs to earn
+in order to have successfully taken the survey. If *Is a Certification* is selected, you can choose
+its template. The certification is automatically emailed to users who have completed the survey.
+
+.. image:: survey/survey-success-percentage.png
+   :align: center
+   :alt: Survey success percentage setting
+
+By activating *Give Badge,* you can select a *Certification Badge* to give to your participants.
+
+.. important::
+   The *Give Badge* feature is **only** available if you enable *Login required* in your survey's
+   options.
+
+Following those configurations, you can choose a survey question that you want to assign a point
+value to, and mark which answer is "correct" on the question pop-up. You can also apply negative
+point results for "incorrect" answers, as well.
+
+.. image:: survey/answers-questions-points.png
+   :align: center
+   :alt: Scoring example of a question
+
+.. _survey/candidates:
+
+Candidates
+----------
+
+In this section, you can decide who can access this survey.
+
+The *Access Mode* allows you to choose between *Anyone with the link* and *Invited people only*.
+You can also decide if you want to grant access to *Appraisal Managers Only*. This person is the
+one who manages the various appraisals/surveys.
+
+You can also require participants to log in to access the survey by ticking *Login Required*.
+
+You can limit the number of login attempts by ticking *Attempts Limit* and entering a number.
+
+.. image:: survey/candidates-section.png
+   :align: center
+   :alt: Candidates section of survey settings
+
+.. _survey/live-session:
+
+Live Session
+------------
+
+This section is dedicated to users who are conducting Live Session surveys, wherein they directly
+engage with an audience at the same time - much like a live event.
+
+Here, you can choose to reward participants with more points for quick answers. So, if more than
+one participant were to choose the correct answer, the quickest (correct) response would be more
+valuable, and thus given more points.
+
+You can also customize the specific *Session Code* that participants would need in order to access
+the Live Session survey here, as well.
+
+.. image:: survey/live-session-setting.png
+   :align: center
+   :alt: Live session section of survey features

content/applications/marketing/survey/overview.rst

@@ -1,10 +0,0 @@
-========
-Overview
-========
-
-.. toctree::
-   :titlesonly:
-
-   overview/create
-   overview/scoring
-   overview/time_random

content/applications/marketing/survey/overview/create.rst

@@ -1,88 +0,0 @@
-========================
-Get Started with Surveys
-========================
-
-Surveys can be used for a range of purposes that can go from collecting customer feedback, evaluate
-the success of an event, measure how pleased customers are with your products/services, gauge
-whether employees are happy and satisfied with their work environment, and even to find out what
-your market is thinking.
-
-Get started
-===========
-
-When creating your survey, choose a *Title* and *Category*. The *Category* field is used to know in
-which context the survey is being conducted, as different applications might use it for different
-purposes such as recruitment, certification, or employee appraisal.
-
-.. image:: media/new_survey.png
-   :align: center
-   :alt: Form view of a survey with a title and category being chosen in Odoo Surveys
-
-Tab: Questions
---------------
-
-| Add sections and questions by clicking on the respective links.
-| On the *Sections and Questions* form, once the question type is chosen and the answer added,
-  under the tab *Options*, enable *Mandatory Answer*, and set an *Error message* to be shown
-  when the user tries to submit the survey without answering the respective question.
-| Depending on the *Question Type*, the tab *Options* aggregates extra and different
-  possibilities. Examples:
-
-- *Single Line Text Box* - can choose a minimum and maximum text length (number of characters -
-  spaces do not count), and its error message.
-- *Multiple choice: multiple answers allowed*: choose between radio buttons or a dropdown menu
-  list, and if you would like to have a comment field. If the user select an answer and type a
-  comment, the values are separately recorded. Or, enable the comment field to be
-  displayed as an answer choice, with which a text type field is displayed.
-- *Matrix Type*: choose if you would like to have one or multiple choices per row.
-
-.. image:: media/sections_questions.png
-   :align: center
-   :alt: Sections and questions view of a survey in Odoo Surveys
-
-Tab: Description
-----------------
-
-Write a *Description* to be displayed under the title of the survey's homepage.
-
-.. image:: media/frontend_description.png
-   :align: center
-   :alt: Frontend of a survey showing the title and description of a survey for Odoo Surveys
-
-.. tip::
-   Click on *Edit* to personalize your pages with the website builder.
-
-Tab: Options
-------------
-
-Under the tab *Options*, choose the *Layout* of your questions. If choosing *One page per section* or
-*One page per question*, an option *Back Button* becomes available, which allows the user to go back
-pages.
-
-.. image:: media/tab_options_layout.png
-   :align: center
-   :alt: Form view of a survey emphasizing the layout feature under options in Odoo Surveys
-
-Test and share the survey
-=========================
-
-| Once your Survey is ready, *Test* it to avoid *Sharing* it with potential errors. As answers get
-  collected, click on *Answers* to access all the details of the respondent and his answers.
-| By default, a filter *Except Test Entries* is applied to keep the list of entries clean with only
-  real participants.
-
-.. image:: media/user_feedback.png
-   :align: center
-   :alt: View list of the participations of a survey in Odoo Surveys
-
-| Another way to access detailed answers is by going to :menuselection:`Participations -->
-  Participations`.
-| Click on *See results* to be redirected to an analytical page.
-
-.. image:: media/analytical_page.png
-   :align: center
-   :alt: View of an analytical page for Odoo Surveys
-
-.. seealso::
-   - :doc:`scoring`
-   - :doc:`time_random`

content/applications/marketing/survey/overview/scoring.rst

@@ -1,36 +0,0 @@
-===============
-Scoring Surveys
-===============
-
-To measure your respondent’s performance, knowledge of a subject, or overall satisfaction, attach
-points to the answers of specific questions. The points are summed up to give your respondent a
-final score.
-
-On your survey’s form, click on *Add a question* and, under the tab *Options*, choose between
-*Scoring with answers at the end* or *Scoring without answers at the end*. Now, on your question’s
-form, set the right answer and score.
-
-.. image:: media/answers_form.png
-   :align: center
-   :alt: Form view of a survey showing a list of answers in Odoo Surveys
-
-Set the percentage score the user needs to achieve to have successfully taken the survey. If
-enabling *Certificate*, choose its template. The certification is automatically sent by email to the
-users who successfully finish it.
-
-.. image:: media/scoring_candidates.png
-   :align: center
-   :alt: Form view of a survey emphasizing the scoring and candidates section in Odoo Surveys
-
-Enable *Login required* to be able to *Give Badges*. Badges are related to the eLearning section of
-your website. Besides the logged-in user, visitors of the website that access the page *Courses*
-can also see the granted badges.
-
-.. image:: media/frontend_bagdes.png
-   :align: center
-   :alt: View of the courses tab emphasizing the latest achievements section on the website for
-         Odoo Surveys
-
-.. seealso::
-   - :doc:`time_random`
-

content/applications/marketing/survey/overview/time_random.rst

@@ -1,34 +0,0 @@
-============================
-Time and Randomize Questions
-============================
-
-Time Limit
-==========
-
-| On timed surveys, respondents need to complete the survey within a certain period of time. It can
-  be used to ensure that all respondents get the same amount of time to find the answers, or to
-  decrease the chance of having them looking at external resources.
-| Set the *Time limit* under the tab *Options*.
-
-.. image:: media/tab_options_timelimit.png
-   :align: center
-   :alt: View of a survey form emphasizing the time limit feature in Odoo Surveys
-
-A timer is shown on the pages so the user can keep track of the remaining time. Surveys not \
-submitted by the *Time limit* do not have their answers saved.
-
-Selection
-=========
-
-| When you randomize a survey, you allow for the questions to be shuffled in a random order every
-  time someone opens the questionnaire. This can be useful to avoid having respondents looking at
-  each others' answers.
-| To do so, under the tab *Options*, enable *Randomized per section*. Now, under the tab *Questions*,
-  set how many of the questions in that section should be taken into account during the shuffling.
-
-.. image:: media/random_question.png
-   :align: center
-   :alt: View of a survey form emphasizing the random questions count column in Odoo Surveys
-
-.. seealso::
-    - :doc:`scoring`

redirects.txt

@@ -203,3 +203,7 @@ purchase/replenishment/flows/compute_date.rst applications/inventory_and_mrp/inv
 purchase/replenishment/flows/purchase_triggering.rst applications/inventory_and_mrp/purchase/products/reordering.rst				# (#814)
 purchase/replenishment/flows/setup_stock_rule.rst applications/inventory_and_mrp/purchase/products/reordering.rst					# (#814)
 purchase/replenishment/multicompany/setup.rst applications/general/multi_companies/manage_multi_companies.rst	# (#814)
+
+content/applications/marketing/survey/overview/create.rst content/applications/marketing/survey.rst # (#928)
+content/applications/marketing/survey/overview/scoring.rst content/applications/marketing/survey.rst # (#928)
+content/applications/marketing/survey/overview/time_random.rst content/applications/marketing/survey.rst # (#928)