[IMP] surveys:update get started docs

closes odoo/documentation#3412

X-original-commit: 3cf6e25f06
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
Signed-off-by: Kevin Scannell (ksc) <ksc@odoo.com>

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

@@ -1,88 +1,224 @@
-========================
+=================
-Get Started with Surveys
+Survey essentials
-========================
+=================
 
-Surveys can be used for a range of purposes that can go from collecting customer feedback, evaluate
+Companies often use surveys to collect valuable information from their customers and employees,
-the success of an event, measure how pleased customers are with your products/services, gauge
+which in turn, allows them to make more informed business decisions.
-whether employees are happy and satisfied with their work environment, and even to find out what
-your market is thinking.
 
-Get started
+In Odoo, surveys are used to collect customer feedback, evaluate the success of a recent event,
-===========
+measure the satisfaction of customers (or employees), and gain more insight into shifting market
+sentiments.
 
-When creating your survey, choose a *Title* and *Category*. The *Category* field is used to know in
+Getting started
-which context the survey is being conducted, as different applications might use it for different
+===============
-purposes such as recruitment, certification, or employee appraisal.
 
-.. image:: create/new_survey.png
+To begin, open the :guilabel:`Surveys` application and click :guilabel:`Create`. Odoo then
+redirects the page to a blank survey template form.
+
+On the survey form, add a :guilabel:`Survey Title` and then add a cover image to the survey by
+hovering over the photo icon and clicking on the :guilabel:`Edit (pencil)` icon. When the file
+explorer window opens, choose an image from the local files.
+
+Below the :guilabel:`Survey Title` are various tabs in which the survey questions and format can be
+created and customized. These tabs are labeled as follows:
+
+- :guilabel:`Questions`: the list of questions to be asked in the survey
+- :guilabel:`Description`: contextual information to aid in understanding the survey
+- :guilabel:`Options`: choices for survey respondents to answer the questions
+
+.. image:: create/questions-description-options.png
    :align: center
-   :alt: Form view of a survey with a title and category being chosen in Odoo Surveys
+   :alt: Various tabs that can be found on the survey template page.
 
-Tab: Questions
+Questions tab
---------------
+=============
 
-| Add sections and questions by clicking on the respective links.
+Add questions and sections to the survey in the :guilabel:`Questions` tab. A section divides the
-| On the *Sections and Questions* form, once the question type is chosen and the answer added,
+survey into parts in order to visually group similar questions together. To make a section, click
-  under the tab *Options*, enable *Mandatory Answer*, and set an *Error message* to be shown
+:guilabel:`Add a section` and type in a section name. Then, add questions or drag and drop
-  when the user tries to submit the survey without answering the respective question.
+questions into the divided sections.
-| 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 -
+Clicking :guilabel:`Add a question` opens the :guilabel:`Create Sections and Questions` pop-up to
-  spaces do not count), and its error message.
+create and customize the survey question.
-- *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:: create/sections_questions.png
+.. image:: create/survey-question-pop-up.png
    :align: center
-   :alt: Sections and questions view of a survey in Odoo Surveys
+   :alt: The survey question pop-up window.
 
-Tab: Description
+Create questions
 ----------------
 
-Write a *Description* to be displayed under the title of the survey's homepage.
+In the :guilabel:`Create Sections and Questions` pop-up, type the question in the
+:guilabel:`Question` field. Then, choose the :guilabel:`Question Type`. A preview of how the
+question type looks is shown in the preview window.
 
-.. image:: create/frontend_description.png
+Choose from the following :guilabel:`Question Types`:
-   :align: center
-   :alt: Frontend of a survey showing the title and description of a survey for Odoo Surveys
 
-.. tip::
+- :guilabel:`Multiple Lines Text Box`
-   Click on *Edit* to personalize your pages with the website builder.
+- :guilabel:`Single Line Text Box`
+- :guilabel:`Numerical Value`
+- :guilabel:`Date`
+- :guilabel:`Datetime`
+- :guilabel:`Multiple choice: only one answer`
+- :guilabel:`Multiple choice: multiple answers allowed`
+- :guilabel:`Matrix`
 
-Tab: Options
+.. note::
+   Different features appear in the :guilabel:`Answers` and :guilabel:`Options` tabs, depending on
+   the :guilabel:`Question Type` chosen. However, the :guilabel:`Description` tab always remains
+   the same, regardless of what question is chosen.
+
+Create sections and questions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once a :guilabel:`Question Type` has been selected, there are three possible tabs where information
+can be customized for the question. These include the :guilabel:`Answers` (if applicable),
+:guilabel:`Description`, and :guilabel:`Options` tabs.
+
+Each tab offers a variety of different features depending on what :guilabel:`Question Type` was
+chosen.
+
+For example, in the :guilabel:`Options` tab, the following options may appear:
+
+- :guilabel:`Mandatory Answer`: the question must be answered.
+- :guilabel:`Matrix Type`: for matrix-type questions, select if one choice or multiple choices can
+  be selected per row.
+- :guilabel:`Number of columns`: select how many columns are displayed.
+- :guilabel:`Images on answers`: allow images on the answer options.
+- :guilabel:`Conditional Display`: determine if the question is displayed based on the
+  participant's answer to a previous question.
+- :guilabel:`Show Comments Field`: allow the participant to type a comment in a text box.
+- :guilabel:`Question Time Limit`: for live session surveys, set a time limit for the question.
+
+Conditional Display
+*******************
+
+:guilabel:`Conditional Display` means the question is only displayed if the specified conditional
+answer has been selected in a previous question.
+
+When the box next to :guilabel:`Conditional Display` is selected, the :guilabel:`Triggering
+Question` field appears. Select a question from the survey.
+
+Then, a :guilabel:`Triggering Answer` field appears. Here, select which answer will trigger this
+:guilabel:`Conditional Display` question.
+
+Options tab
+===========
+
+Back on the main survey template form, under the :guilabel:`Options` tab, there are different
+sections of settings that can be modified.
+
+The sections include:
+
+- :guilabel:`Questions`: focuses on the overall presentation of the survey
+- :guilabel:`Scoring`: decides how the survey is scored
+- :guilabel:`Candidates`: manages access to the survey
+- :guilabel:`Live Session`: enables the survey into a real-time group activity.
+
+Questions
+---------
+
+First, select the :guilabel:`Layout` of the survey. The following options can be chosen:
+
+- :guilabel:`One page with all the questions`
+- :guilabel:`One page per section`
+- :guilabel:`One page per question`
+
+If either the :guilabel:`One page per section` or :guilabel:`One page per question` options are
+chosen, then the :guilabel:`Back Button` option appears. If selected, the :guilabel:`Back Button`
+option allows the participant to go back to a question during the survey.
+
+Under the :guilabel:`Layout` options is the :guilabel:`Progression Mode` setting, which indicates
+how the participant's progress during the survey is displayed. It is shown as either a
+:guilabel:`Percentage` or a :guilabel:`Number`.
+
+Next, there is an option available to add a :guilabel:`Survey Time Limit`. To implement this
+option, simply check the box, and enter the amount of time (in minutes) participants have to
+complete the survey.
+
+After the :guilabel:`Survey Time Limit` option is a section labeled :guilabel:`Selection`. Here,
+questions can be :guilabel:`Randomized per section`, in other words, the number of random questions
+can be configured by section. This mode is ignored in a live session.
+
+.. seealso::
+   :doc:`time_random`
+
+Scoring
+-------
+
+The following options are available when deciding how a :guilabel:`Scoring` method:
+
+- :guilabel:`No scoring`
+- :guilabel:`Scoring with answers at the end`
+- :guilabel:`Scoring without answers at the end`
+
+If either the :guilabel:`Scoring with answers at the end` or :guilabel:`Scoring without answers at
+the end` options are selected, a :guilabel:`Success %` field appears. Set the percentage of correct
+answers needed to pass the survey.
+
+Next, there is the option to make the survey a certification. To do so, check the box next to the
+option labeled :guilabel:`Is a Certification`, and two additional fields appear. Select a color
+theme in the :guilabel:`Certification Template` field and then choose an :guilabel:`Email
+Template`. When a participant passes the certification with the required score, an email from Odoo
+will automatically be sent to that person using the selected email template.
+
+If the :guilabel:`Give Badge` feature is enabled and the :guilabel:`Certification Badge` is set,
+the survey participant also receives a badge upon passing the certification.
+
+.. seealso::
+   :doc:`scoring`
+
+Candidates
+----------
+
+To determine access to the survey, the :guilabel:`Access Mode` has two options to choose between:
+:guilabel:`Anyone with the link` and :guilabel:`Invited people only`.
+
+Below the :guilabel:`Appraisal Managers Only` checkbox is the :guilabel:`Login Required` option to
+require a login to participate in the survey. If this option is activated, an :guilabel:`Attempts
+Limit` field also populates, in which the number of survey attempts is defined for the participant.
+
+Live Session
 ------------
 
-Under the tab *Options*, choose the *Layout* of your questions. If choosing *One page per section* or
+The :guilabel:`Live Session` section is dedicated to users who are conducting surveys in real-time,
-*One page per question*, an option *Back Button* becomes available, which allows the user to go back
+wherein they directly engage with and collect answers from a live audience.
-pages.
 
-.. image:: create/tab_options_layout.png
+Customize the :guilabel:`Session Code` here; this code is needed for participants to access the
-   :align: center
+live session survey. Reward participants for quick answers by selecting the checkbox labeled
-   :alt: Form view of a survey emphasizing the layout feature under options in Odoo Surveys
+:guilabel:`Reward quick answers`. By checking it, attendees will get more points if they answer
+quickly.
+
+Description tab
+===============
+
+Back on the main survey template page is the :guilabel:`Description` tab, where a custom
+description of the survey can be added. This is displayed beneath the title on the survey's
+homepage, which is on the front end of the website made through the Odoo :guilabel:`Website` app.
 
 Test and share the survey
 =========================
 
-| Once your Survey is ready, *Test* it to avoid *Sharing* it with potential errors. As answers get
+Once the survey is created and saved, run a test to check for possible errors before finally
-  collected, click on *Answers* to access all the details of the respondent and his answers.
+sending it out to the participants by clicking :guilabel:`Test` in the upper left corner of the
-| By default, a filter *Except Test Entries* is applied to keep the list of entries clean with only
+survey template page.
-  real participants.
 
-.. image:: create/user_feedback.png
+When activated, Odoo redirects the page to a test version of the survey on the front end of the
-   :align: center
+website. This page displays how the survey will look to participants. Proceed to run through the
-   :alt: View list of the participations of a survey in Odoo Surveys
+survey, like a normal participant, to check for errors.
 
-| Another way to access detailed answers is by going to :menuselection:`Participations -->
+To return to the survey template form in the backend, simply click the :guilabel:`This is a test
-  Participations`.
+survey. Edit Survey` link in the blue banner along the top of the page. Once Odoo redirects the
-| Click on *See results* to be redirected to an analytical page.
+page to the survey template in the backend, make any further changes, as needed, before officially
+sending the survey out to participants.
 
-.. image:: create/analytical_page.png
+When the survey is ready to be shared with the audience, click the :guilabel:`Start Survey` button
-   :align: center
+in the upper-left corner of the survey template form. Then, click :guilabel:`Share`.
-   :alt: View of an analytical page for Odoo Surveys
 
-.. seealso::
+In the pop-up window, add the survey recipients in the :guilabel:`Recipients` field (for existing
-   - :doc:`scoring`
+contacts in the Odoo database) or the :guilabel:`Additional emails` field (for contacts that do not
-   - :doc:`time_random`
+want to be listed in the Odoo database). Finally, click :guilabel:`Send`.
+
+As answers are received, check them by clicking the :guilabel:`Answers` smart button on the survey
+template form, or the :guilabel:`See Results` button in the upper left corner. To end the survey,
+click the :guilabel:`Close` button on the survey template form.

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

@@ -1,35 +1,56 @@
 ===============
-Scoring Surveys
+Scoring surveys
 ===============
 
-To measure your respondent’s performance, knowledge of a subject, or overall satisfaction, attach
+To measure a survey participant's performance, knowledge, or overall satisfaction, Odoo ascribes
-points to the answers of specific questions. The points are summed up to give your respondent a
+points to survey answers. At the end of the survey, these points are summed up, resulting in the
-final score.
+participant's final score.
 
-On your survey’s form, click on *Add a question* and, under the tab *Options*, choose between
+To add points to questions, open the :guilabel:`Surveys` application, choose the desired survey
-*Scoring with answers at the end* or *Scoring without answers at the end*. Now, on your question’s
+form, and then click on the :guilabel:`Options` tab. Under the :guilabel;`Scoring` section, choose
-form, set the right answer and score.
+between :guilabel:`Scoring with answers at the end` or :guilabel:`Scoring without answers at the
+end`.
 
-.. image:: scoring/answers_form.png
+- :guilabel:`Scoring with answers at the end` shows the survey participant their answers after
+  completing the survey, and displays which questions they got right or wrong. On questions where
+  there was an incorrect answer, the correct answer will be highlighted.
+
+- :guilabel:`Scoring without answers at the end` does not show the survey participant their answer
+  choices after completing the survey, only their final score.
+
+To indicate correct answers, click on the :guilabel:`Questions tab` and choose a question. In the
+question form, check the :guilabel:`Is a correct answer` box for the choice that is the correct
+answer and attach a score value.
+
+Back on the :guilabel:`Options` tab of the survey, set the :guilabel:`Success %`. The percentage
+entered determines what percentage of correct answers is needed to pass the survey.
+
+Further on the :guilabel:`Options` tab of the survey, survey administrators can also choose to make
+the survey a certification. A certification indicates that the survey asks questions to test the
+participants' knowledge level on a subject.
+
+When enabling the :guilabel:`Is a certification` option, choose a :guilabel:`Certification email
+template`. The certification will automatically be emailed using this email template to users who
+pass the survey with a final score that is greater than or equal to the set :guilabel:`Success %`.
+
+In the :guilabel:`Candidates` section, participants can be required to log in to take the survey.
+If the :guilabel:`Login Required` setting is enabled, two new options appear: the
+:guilabel:`Attempts Limit` checkbox, which limits the number of times a participant can attempt
+the survey, and the option to :guilabel:`Give Badge`, located beneath the :guilabel:`Certification`
+options in the :guilabel:`Scoring` section.
+
+.. image:: scoring/required-score-login.png
    :align: center
-   :alt: Form view of a survey showing a list of answers in Odoo Surveys
+   :alt: Setting the Required Score (percentage), login required, and certification template.
 
-Set the percentage score the user needs to achieve to have successfully taken the survey. If
+Badges are displayed on the eLearning portion of a given user's portal, and are a way to set
-enabling *Certificate*, choose its template. The certification is automatically sent by email to the
+milestones and reward participants for passing surveys or gaining points. Besides the awardee,
-users who successfully finish it.
+website visitors who access the :guilabel:`Courses` page will also be able to see the granted
+badges.
 
-.. image:: scoring/scoring_candidates.png
+.. image:: scoring/frontend-badges.png
    :align: center
-   :alt: Form view of a survey emphasizing the scoring and candidates section in Odoo Surveys
+   :alt: Example of how a badge looks on the eLearning portion of the website.
-
-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:: scoring/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`
+   :doc:`time_random`

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

@@ -1,34 +1,48 @@
-============================
+==============================
-Time and Randomize Questions
+Timed and randomized questions
-============================
+==============================
 
-Time Limit
+When creating a survey in Odoo, there are options to set a time limit on the survey and randomize
+the questions.
+
+Time limit
 ==========
 
-| On timed surveys, respondents need to complete the survey within a certain period of time. It can
+During a timed survey, participants must finish the survey within a specified period of time.
-  be used to ensure that all respondents get the same amount of time to find the answers, or to
+A common use case for implementing a time limit is that it greatly reduces the chance of
-  decrease the chance of having them looking at external resources.
+participants looking up responses via external resources (e.g. web search), and reduces the survey
-| Set the *Time limit* under the tab *Options*.
+to a "closed book" testing environment.
 
-.. image:: time_random/tab_options_timelimit.png
+Find the :guilabel:`Survey Time Limit` setting in the :guilabel:`Options` tab of the survey form,
+under the :guilabel:`Questions` section.
+
+.. image:: time_random/time-limit.png
    :align: center
-   :alt: View of a survey form emphasizing the time limit feature in Odoo Surveys
+   :alt: Time limit field in the options tab of a survey template form.
 
-A timer is shown on the pages so the user can keep track of the remaining time. Surveys not \
+When the :guilabel:`Survey Time Limit` option is checked, a timer will be displayed on every page
-submitted by the *Time limit* do not have their answers saved.
+of the survey, letting participants keep track of the time remaining while the survey is active.
 
-Selection
+.. note::
-=========
+   Participants that do not submit their survey by the preconfigured time limit will *not* have
+   their answers saved.
 
-| When you randomize a survey, you allow for the questions to be shuffled in a random order every
+Randomized selection
-  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:: time_random/random_question.png
+When a survey is randomized, Odoo shuffles the questions and reveals them in a random order every
+time a participant begins the questionnaire. Using randomization as a survey method discourages
+participants from looking at each other's responses, and helps control for individual testing.
+
+To randomize a survey, click the :guilabel:`Options` tab on the survey form. In the
+:guilabel:`Questions` section, select :guilabel:`Randomized per section` for the
+:guilabel:`Selection` field. After enabling, navigate to the :guilabel:`Questions` tab and look in
+the :guilabel:`Random questions count` column. From there, determine how many questions (per
+section) Odoo should select and display during the shuffling of questions.
+
+.. image:: time_random/random-questions.png
    :align: center
-   :alt: View of a survey form emphasizing the random questions count column in Odoo Surveys
+   :alt: Randomized question count in the questions tab of a survey.
 
 .. seealso::
-    - :doc:`scoring`
+   :doc:`scoring`