Difference between revisions of "Review"

From ImpVis Wiki
Jump to navigation Jump to search
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''The writers and peers'''
Any particular visualisation, or new version of an existing visualisation, must be reviewed before it is published on the website. This keeps up the quality of the content! When a creator [[Uploading a new visualisation|uploads a visualisation]], they will specify reviewers. This should include at least one staff member - usually the staff partner of the project. Only when all reviewers have approved the visualisation can it be published on the website.


Any particular visualisation must be reviewed before it is incorporated into the website. This keeps up the quality of the content! Here is a set of questions a vis writer can ask as an initial review:
== Appointing reviewers ==
The creator of the visualisation can appoint any existing ImpVis user as a reviewer for their visualisation, or invite new users to join ImpVis and review their visualisation (see [[uploading a new visualisation]] for how to do this). However, it is advisable that you only choose people who are expecting to review your visualisation, otherwise it is likely that they will not undertake the review and your visualisation will be stuck in the review stage!


# Has the vis achieved the primary learning outcome?
When selecting reviewers, as well as including your project partners, it is useful if you can also get someone with “clean eyes”: either someone who has not seen the subject you’re trying to teach yet or someone who has not seen your visualization trying to teach the content you’re doing. Peers are an excellent choice! This peer review gives you feedback on how easy it is to understand what’s been said.
# Is the vis physically correct or at least visually giving the right intuition?
# Is it intuitive to use?


And for a suite:
You can also appoint new reviewers or remove existing ones after the uploading process. The latter is advised if the reviewer is unresponsive. See [[Managing your visualisation#Reviewers and developers|here]] for an explanation on how to do this.


# Has the suite achieved secondary learning outcomes?
== Becoming a reviewer ==
# Does every vis work correctly/the way you want?
If you have been asked to review a visualisation, you will receive an automated email with a link to the visualisation to review.  '''''Please be aware that the visualisation cannot be published until you have finished your review!''''' If you do not wish to undertake this task, do let the visualisation creator know so they can appoint somebody else.
# Does it flow?
# Is it easy to follow through?


(Bug check: Have you looked into exceptional cases if they exist?)
If you have not yet registered on the [https://impvis.co.uk ImpVis] website, the automated review email will ask you to [https://impvis.co.uk/signup sign up], which is a simple process. When you are an ImpVis user (i.e. registered on the ImpVis website), you have access to the '[https://impvis.co.uk/code/dashboard MyVis]' environment on the website.


At this point, it’s best if you can get someone with “clean eyes,” either someone who has not seen the subject you’re trying to teach yet or someone who has not seen your visualization trying to teach the content you’re doing. Peers are an excellent choice! This peer review gives you feedback on how easy it is to understand what’s been said.
When you are a reviewer for a visualisation, the visualisation will show up on your '[https://impvis.co.uk/code/dashboard MyVis]' dashboard, underneath your [[Favourite visualisations and Collections|favourite]] visualisations and collections, as shown in the screenshot below.
[[File:Dashboard for reviewer.png|alt=Dashboard showing the visualisation awaiting your review under your favourite collections and visualisations.|center|thumb|600x600px|Dashboard showing the visualisation awaiting your review.]]
You may note that if you have previously reviewed any visualisations, these will also remain on your dashboard under 'Your Past Approvals'.


You can click 'View' to see the visualisation you have been asked to review. You will see the following screen:
[[File:Reviewing a visualisation.png|alt=Reviewer's view of the visualisation to review|center|thumb|600x600px|Reviewer's view of the visualisation to review]]
Here you can see the details of the visualisation you are reviewing. Note at the top left that you are currently in the 'Overview' tab - you will need to return to this tab later when you have finalised your review. Now, to launch the visualisation, press the 'Launch' button - the visualisation itself will open in a new tab.


== Undertaking the review ==
After launching the visualisation, you can explore the visualisation in one browser tab whilst recording any issues you encounter in the other.


'''Consulting an academic'''
Here is a set of questions to consider when undertaking your review:


This document is not quite complete, needs expanidng on the sections of
# Does the visualisation achieve the intended learning outcomes? The intended learning outcomes should be listed on the visualisation's Wiki page - the URL is listed in the 'Overview' tab you launched the visualisation from. If you cannot find the learning outcomes, please contact the creator!
# Is the visualisation intuitive to use? Is there a clear learning journey for the learner to follow?
#Is the text accompanying the visualisation clear and correct?
#Are there any bugs or mistakes? Does the visualisation work correctly for extreme cases of input values?
#Is there any way in which the visualisation could be improved?
 
If you are a staff partner on the project reviewing the visualisation, your review is very important: it is your responsibility to check that:
 
# the visualisation is physically/mathematically correct, or at least visually gives the right intuition (approximations be used rather than exact models, this is fine as long as it leads the learner to the correct conclusions).
# the visualisation is suitable for your intended implementation, i.e. it is at the right level for your students and fits within the learning setting you want it to be used in.
 
If you encounter any issues with the visualisation that you wish to feed back, please read the following section. If you have not found any issues and have no suggestions for further work, skip ahead to [[Review#Finishing your review|Finishing your review]].
 
== Recording issues ==
When you encounter any issues or would like to feed back suggestions for future work, please think carefully about their priority:
 
* Low priority: suggestions for further work or improvements
* Medium priority: recommended improvements, either cosmetic or functional. these are issues that you think should be fixed, but the visualisation can be used by learners in the mean time. For example, text that overlaps graphics, typos in the text, small bugs that don't stop the visualisation from being used, etc.
* High priority: critical issues that need to be fixed before the visualisation can be used by students, for example serious bugs or errors. The visualisation '''''cannot''''' '''''be published''''' with any outstanding high-priority issues - a new version will need to be uploaded and reviewed first. Note that for this reason, high-priority issues can only be recorded for visualisations that are currently in review - for approved visualisations only low- and medium-priority issues are available.
 
To record your issues, click on the 'Issues' tab on the top left of the page from which you launched the visualisation (see screenshot above). You will then see the following:
[[File:Issues list.png|alt=Issues list - record new issues here.|center|thumb|600x600px|Issues list - record new issues here.]]
At the top, the three priorities are summarised. Below that, you can see any issues that have been raised already - do read through these to check whether somebody else has already recorded the issue you found. At the bottom, you can record new issues. Type the description of your issue in the textbox - please be specific so that it is clear for the developers when or where your issue occurs, or what exactly you think should be included in any future improvements. Below the description, specify the priority (low, medium, or high) from the dropdown box before pressing 'Submit'.
 
You can edit or delete issues you recorded by pressing the pencil symbol or the cross symbol next to the issue.
 
Every time you record an issue, the developer(s) will be notified by email.
 
== Finishing your review ==
When you have finished your review, you need to click the green 'Finish review' button in the 'Overview' tab as shown in the screenshot above. At this point, the developers will be notified that you have finished your review. You can still resume your review as long as the visualisation remains 'in review' (i.e. it isn't approved yet) by clicking the 'Resume review' button. If the visualisation is already approved, you will not have the option to resume your review.
 
Once all reviewers have finished their review and if only low- and medium-priority issues (or none at all) have been recorded, the visualisation is approved. It will now be published automatically to the '[https://impvis.co.uk/teach Teach]' environment of the website. If any high-priority issues were raised, the visualisation will not be approved. The developer will need to upload a new version; they will specify which issues they resolved in the new version and you will be asked to review the latest version again to ensure you are satisfied.
 
== Past approvals ==
Any visualisations you have previously approved are shown at the bottom of your '[https://impvis.co.uk/code/dashboard MyVis]' dashboard, under 'Past Approvals'. You can still view these visualisations and record issues, though you will not be able to record any high-priority issues.
 
[[Category:ImpVis Website Guidance]]

Latest revision as of 12:32, 1 October 2021

Any particular visualisation, or new version of an existing visualisation, must be reviewed before it is published on the website. This keeps up the quality of the content! When a creator uploads a visualisation, they will specify reviewers. This should include at least one staff member - usually the staff partner of the project. Only when all reviewers have approved the visualisation can it be published on the website.

Appointing reviewers

The creator of the visualisation can appoint any existing ImpVis user as a reviewer for their visualisation, or invite new users to join ImpVis and review their visualisation (see uploading a new visualisation for how to do this). However, it is advisable that you only choose people who are expecting to review your visualisation, otherwise it is likely that they will not undertake the review and your visualisation will be stuck in the review stage!

When selecting reviewers, as well as including your project partners, it is useful if you can also get someone with “clean eyes”: either someone who has not seen the subject you’re trying to teach yet or someone who has not seen your visualization trying to teach the content you’re doing. Peers are an excellent choice! This peer review gives you feedback on how easy it is to understand what’s been said.

You can also appoint new reviewers or remove existing ones after the uploading process. The latter is advised if the reviewer is unresponsive. See here for an explanation on how to do this.

Becoming a reviewer

If you have been asked to review a visualisation, you will receive an automated email with a link to the visualisation to review. Please be aware that the visualisation cannot be published until you have finished your review! If you do not wish to undertake this task, do let the visualisation creator know so they can appoint somebody else.

If you have not yet registered on the ImpVis website, the automated review email will ask you to sign up, which is a simple process. When you are an ImpVis user (i.e. registered on the ImpVis website), you have access to the 'MyVis' environment on the website.

When you are a reviewer for a visualisation, the visualisation will show up on your 'MyVis' dashboard, underneath your favourite visualisations and collections, as shown in the screenshot below.

Dashboard showing the visualisation awaiting your review under your favourite collections and visualisations.
Dashboard showing the visualisation awaiting your review.

You may note that if you have previously reviewed any visualisations, these will also remain on your dashboard under 'Your Past Approvals'.

You can click 'View' to see the visualisation you have been asked to review. You will see the following screen:

Reviewer's view of the visualisation to review
Reviewer's view of the visualisation to review

Here you can see the details of the visualisation you are reviewing. Note at the top left that you are currently in the 'Overview' tab - you will need to return to this tab later when you have finalised your review. Now, to launch the visualisation, press the 'Launch' button - the visualisation itself will open in a new tab.

Undertaking the review

After launching the visualisation, you can explore the visualisation in one browser tab whilst recording any issues you encounter in the other.

Here is a set of questions to consider when undertaking your review:

  1. Does the visualisation achieve the intended learning outcomes? The intended learning outcomes should be listed on the visualisation's Wiki page - the URL is listed in the 'Overview' tab you launched the visualisation from. If you cannot find the learning outcomes, please contact the creator!
  2. Is the visualisation intuitive to use? Is there a clear learning journey for the learner to follow?
  3. Is the text accompanying the visualisation clear and correct?
  4. Are there any bugs or mistakes? Does the visualisation work correctly for extreme cases of input values?
  5. Is there any way in which the visualisation could be improved?

If you are a staff partner on the project reviewing the visualisation, your review is very important: it is your responsibility to check that:

  1. the visualisation is physically/mathematically correct, or at least visually gives the right intuition (approximations be used rather than exact models, this is fine as long as it leads the learner to the correct conclusions).
  2. the visualisation is suitable for your intended implementation, i.e. it is at the right level for your students and fits within the learning setting you want it to be used in.

If you encounter any issues with the visualisation that you wish to feed back, please read the following section. If you have not found any issues and have no suggestions for further work, skip ahead to Finishing your review.

Recording issues

When you encounter any issues or would like to feed back suggestions for future work, please think carefully about their priority:

  • Low priority: suggestions for further work or improvements
  • Medium priority: recommended improvements, either cosmetic or functional. these are issues that you think should be fixed, but the visualisation can be used by learners in the mean time. For example, text that overlaps graphics, typos in the text, small bugs that don't stop the visualisation from being used, etc.
  • High priority: critical issues that need to be fixed before the visualisation can be used by students, for example serious bugs or errors. The visualisation cannot be published with any outstanding high-priority issues - a new version will need to be uploaded and reviewed first. Note that for this reason, high-priority issues can only be recorded for visualisations that are currently in review - for approved visualisations only low- and medium-priority issues are available.

To record your issues, click on the 'Issues' tab on the top left of the page from which you launched the visualisation (see screenshot above). You will then see the following:

Issues list - record new issues here.
Issues list - record new issues here.

At the top, the three priorities are summarised. Below that, you can see any issues that have been raised already - do read through these to check whether somebody else has already recorded the issue you found. At the bottom, you can record new issues. Type the description of your issue in the textbox - please be specific so that it is clear for the developers when or where your issue occurs, or what exactly you think should be included in any future improvements. Below the description, specify the priority (low, medium, or high) from the dropdown box before pressing 'Submit'.

You can edit or delete issues you recorded by pressing the pencil symbol or the cross symbol next to the issue.

Every time you record an issue, the developer(s) will be notified by email.

Finishing your review

When you have finished your review, you need to click the green 'Finish review' button in the 'Overview' tab as shown in the screenshot above. At this point, the developers will be notified that you have finished your review. You can still resume your review as long as the visualisation remains 'in review' (i.e. it isn't approved yet) by clicking the 'Resume review' button. If the visualisation is already approved, you will not have the option to resume your review.

Once all reviewers have finished their review and if only low- and medium-priority issues (or none at all) have been recorded, the visualisation is approved. It will now be published automatically to the 'Teach' environment of the website. If any high-priority issues were raised, the visualisation will not be approved. The developer will need to upload a new version; they will specify which issues they resolved in the new version and you will be asked to review the latest version again to ensure you are satisfied.

Past approvals

Any visualisations you have previously approved are shown at the bottom of your 'MyVis' dashboard, under 'Past Approvals'. You can still view these visualisations and record issues, though you will not be able to record any high-priority issues.