ISCAN – Getting Help and Giving Feedback

Below is a guide on how to get help with large and small questions, as well as how to give feedback about the ISCAN User Interface.

Feedback

If you are using the ISCAN user interface, we are relying on your feedback for improvements. Providing feedback as you go through a tutorial or general testing is crucial to us. If you encounter any difficulties you believe may be a bug, we want to hear about it. We are also especially interested in feedback on what aspects you found confusing, or how the general design and User Interface should change to improve general usability.

To log bugs, enhancements (something which is not a bug, but which should definitely be done for the software to work better or be more useful to you), and suggestions (an idea about a feature that could change or be added, but which is not strictly necessary), we are using GitHub issues.

Getting Started in GitHub

In order to post an issue, you must have a GitHub account. Thankfully setting one up is straightforward. Start by going to https://github.com/join and following the steps provided to create your account.

Check out this link for a general introduction to GitHub. It is a tutorial designed to teach you all of the important GitHub basics in less than an hour.

Filing an Issue

Once you have a GitHub account, you can visit the development repository used for issues with the following link: https://github.com/MontrealCorpusTools/polyglot-server

In the navigation bar, select Issues. Here you can browse through existing issues and post a new issue.

Browse Issues

It is possible that someone has encountered the same bug, or has thought of a similar enhancement suggestion, so it is good to take a look through these to avoid duplicates. Conveniently, you can search the list of issues by typing in the box next to Filters dropdown menu. For example, if you have a suggestion for an enhancement of the Query View*, you may type “query” into the search box to find related existing issues.

You can also query issues using the ‘Labels’ button next to the search box. If you wish to see closed issues also, then simply remove the automatic “is:open” input in the search box.

If the issue already exists, please add a comment to say that you agree with this issue or to help clarify or specify the problem/suggestion. If you find no existing issues related to your question or comment, please post a new issue.

Post a new Issue

In order for your issue to be most helpful for those developing ISCAN, here are some guidelines:

General:

  • Post screenshots liberally – to clarify your description of the bug/enhancement request/suggestion.
  • Add labels – to help categorize your issue and ensure it is appropriately dealt with (see next section for more details).
  • Specify your web browser and server – as this will make subtle differences to the web based user interface (example: “… using Firefox/Chrome, with ISCAN running on Roquefort server”)

For a Bug:

  • Be specific about what you were doing when you encountered the bug (what view* you were in, what you were trying to do, what went wrong). Provide the sequence of steps required to reproduce the bug. Ideally, the developers will be able to recreate the error you encountered using these steps.
  • Provide details if you tried to work around or resolve the problem, even if it didn’t work.

For an enhancement or suggestion:

  • Be specific in your description of your suggestion and how it would improve the user interface or make something more clear.
  • In general, a good format for these is: Improve X by doing/adding Y because Z

Here is an example of a good Bug Report:

Here is an example of a good Enhancement Issue:

Here is an example of a good Suggestion/Feature Request:

Here is a general guide on how to post issues if you need extra help.

Labels

To help ensure that your issue is dealt with properly, and in a timely fashion, please be sure to add appropriate tags, or labels, to your issue. For example, if you encountered a bug in the Query View (for example, an ‘Add Filter’ button which has no effect when pressed), you may use the ‘Query’ and ‘Bug’ labels for the issue you post.

Here are the most common labels you may use to post issues.

  • bug – If you encounter an error
  • enhancement – For something that is not a bug, but should definitely be changed
  • suggestion – For ideas on how to improve ISCAN usability
  • question – For information on how to do x in ISCAN
  • UI – If your issue relates in any way to the ISCAN Graphical User Interface
  • import – If your issue relates to importing a corpus
  • enrichment – For issues having to do with enrichments or the Enrichment View*
  • query – For issues having to do with queries or the Query View
  • export – For issues with exporting
  • inspection – For issues related to the details/inspection view

Help

If at any point while testing or following a tutorial, you have some questions about how to do something in polyglot-ISCAN, follow the steps below to get help.

Quick Help

There is a Slack channel dedicated to users who have a quick question about anything they can’t figure out in ISCAN who would like real-time help. If you are already on the McGill Linguistics Labs Slack workspace then you can post your questions in the #iscan-help channel.

Getting Started in Slack

If you do not already have a Slack account, you can easily join. The first step is to email Vanna (savanna.willerton@mail.mcgill.ca) to ask to join the McGill Linguistics Labs workspace to use the iscan-help channel’ (<– you can just copy paste this as the email body if you’d like). Once I receive this, I will send you an email invitation to the workspace.

You will be prompted to create a Slack account and set up your profile. Once you have done this you will automatically have access to the iscan-help channel and can begin posting questions.

Here is a resource on getting started with Slack.
And here is another for joining a workspace.

Longer/More Involved Help Required

Using the steps in Feedback above, post your question as an issue on GitHub (here: https://github.com/MontrealCorpusTools/polyglot-server). Just be sure to use the question and/or help wanted labels, along with other relevant labels, when posting a question as an issue.

*

Corpus View: This is the page you see when you select a corpus from the ‘Corpora’ dropdown menu on the navigation bar. As you add enrichments, more information will appear on this page to reflect these. From this page you can access the Enrichment and Query views.

Enrichment View: This is the page you access by pressing the ‘Create, run, and edit enrichments’ button under the ‘Enrichments’ header in the Corpus View. It contains a table populated with existing enrichments.

Query View: This is the page you access by choosing the ‘New query’ or ‘Open selected query’ buttons. In this page you run searches through your database and export list of objects found.