Help tour for the graph editor

[maxkfranz]

Description

Q: What is the name of the feature?

A: Help tour

Q: What does this feature enable the user to do?

A: This feature gives the user an overview of the app.

Q: What information must the user provide to use the feature?

A: The textmining input must be provided, by the user or by the system, in order to show the paper's prepopulated network.

Q: What are the applicable constraints, e.g. compatibility or performance?

A:

• The tour can't take up much of the user's time. It should take under a minute.
• The tour should be able to be modified slightly in order to fit in the form interface.

Q: How does this feature affect each class of user (persona)?

A:

• Biologist:
  • A bench biologist not be familiar with as much jargon as other users.
  • The tour gives a sense of how biological concepts are represented.
  • The tour let's the user know
• Editor:
  • The tour helps the editor better understand the process that an author would go through.
• Computational biologist:
  • The tour gives a sense of how biological concepts are represented: This let's the computational biologist understand what our model is like.
• Curator:
  • The tour isn't as useful to power users like curators.

Specification

Mockup

Phase 1 : Welcome to Factoid

---

Phase 2 : Adding entities

---

Phase 3 : Adding interactions

---

Phase 4 : Submit

---

Phase 5 : Prepopulation

Details

Notes:

• Annotations in red.
• The user can go to any phase using the skipper at the bottom-centre of the screen.
• Each phase contains a set of numbered animation steps.
  • Each step is animated with a spotlight to focus the user on the area of interest. Everything but the spotlight area is darkened.
  • Each step shows the interface as it would behave if a the user were interacting with it.
  • A fake cursor may be needed for some animation steps. It must be obvious to the user that it's a fake cursor -- semitransparency on the cursor may help.
  • Each step automatically progresses in turn.
  • Each step has a short subtitle underneath the spotlight.
• After the animation steps are finished for a phase, the phase summary is shown at the bottom of the screen. The summary is a very small amount of text -- about one line per item.
• A large, salient "OK" button lets the user easily find where to click to go to the next phase. The text on the "OK" button may be "Next".

Phases:

• (1) Welcome to Factoid
  • There are no animation steps for this phase. The summary is immediately shown.
  • Summary: Factoid is an app that helps authors capture the biology in their papers into an unambiguous digital format at the time of publication. This tour shows you how to use the app, from beginning to end.
• (2) Adding entities
  • Animation steps:
  • (1) An entity is a physical thing, such as a protein. To add one, start by clicking the circle icon.
  • (2) A new entity is shown here, at the top-left.
  • (3) Name the entity.
  • (4) Select the best known match. This really helps to make the digital files better!
  • (5) You're done adding the entity.
  • Summary: An entity is a physical thing, such as a protein. To create an entity, click the circle icon, name the entity, and finally specify the best known match.
• (3) Adding interactions
  • Animation steps:
  • (1) An interaction is a relationship, e.g. phosphorylation, between two entities. Here's one entity.
  • (2) Here's another entity.
  • (3) To add an interaction, start by clicking the line icon.
  • (4) Click and drag from the first entity to the second one to draw the line.
  • (5) Select the interaction type.
  • (6) Select the arrow type (activation/inhibition) and direction.
  • (7) You're done adding the interaction.
  • Summary: An interaction is a relationship, e.g. phosphorylation. To create an interaction, click the line icon, click and drag from one entity to the other, select the type (e.g. phosphorylation), and finally select either an activation or inhibition arrow.
• (4) Submitting
  • Animation steps:
  • (1) Review to ensure all entities and interactions are correct. You can amend an entity or an interaction by clicking the pencil icon.
  • (2) Click submit when you're done. Once you've confirmed your submission, it will be sent so that it can be distributed by your publisher.
  • Summary: Review your figure to ensure that all entities and interactions are correct. When you're satisfied with the result, click the submit button and confirm.
• (5) Prepopulation : Your paper
  • Note that the "OK" button is "Done" now, since this is the last phase.
  • Animation steps:
  • (1)
    • Empty textmining result: Factoid wasn't able to find any entities or interactions for your paper. You'll have to add them yourself.
    • Non-empty textmining result: Factoid guessed that these entities and interactions are in your paper.
  • (2) Edit the entities and interactions until you are satisfied with them for publication.
  • Summary:
  • Empty textmining result: Factoid couldn't find entities and interactions for your paper, so you'll have to add them yourself.
  • Non-empty textmining result: Factoid was able to guess some entities and interactions for your paper. You'll have to amend the document to make sure that it's correct and complete.

[d2fong]

General note

1. I think contractions should be avoided in formal writing

Consistent Language

I think we need consistent language for the following:

• Should the language imply that "Factoid" performed actions e.g. Factoid recognized the following entities vs The following entities were recognized in your paper
• What name should we present to the user to represent the internal concept of document under. In the current text it is referred to as 'biology in their paper', 'result', and 'figure'. Internally, we call it a document, or network, or result. I think it would be good to have a common grounding that we can all use to refer to this concept when introducing it to users.
• Words to describe the idea that factoid could be wrong in relation to the extracted entities and interactions:
  • (Original copy): Factoid guessed ...
  • The following interactions and entities were found to be associated with the results of your paper, please ensure that the extracted entities and interactions correctly represent the result of your paper.
  • Factoid suspects the following entities and interactions were found in your paper
  • The following interactions and entities could be related to the results of your paper
  • Other terms: 'supposes', 'theorizes', 'assumes', 'speculates'

Proposed edits

1. Summary: Factoid is an app that helps authors digitize the biological results of their papers as a part of the publication process.

2.1: An entity is a physical thing such as a chemical or protein. Add an entity by clicking the circle icon.

2.4: Make your entity unambiguous. Provide common ground to help you precisely communicate to others which entity you are referring to in your paper.

4.1: Ensure all entities and interactions are correct. You can edit an entity or interaction by clicking the pencil icon.

4.2: Click submit when you are done. Once confirmed, your submission will be sent to your publisher for distribution.

5.1 Empty textmining result: No interactions or entities were recognized from your paper. Please add the results of your paper manually.

5.1 Non-empty textmining result: The following interactions and entities were derived from your paper, but they may be in an incomplete state. Please edit or add new entities until the figure represents the results of your paper.

5.2 Edit or add new entities and interactions until the figure represents the results of your paper.

5.Summary Empty textmining result: No interactions or entities were recognized from your paper. Please add the results of your paper manually.

Non-empty textmining result: The following entities and interactions were extrapolated for your paper. Edit or add new entities and interactions until the figure represents the results of your paper.

[sacdallago]

A general note

the text etc. seems to be very biased towards the scenario: author publishes with journal, journal sends email out to author. While this is most likely the case, I would keep the text as agnostic as possible.

---

Text suggestions:

FYI: I put the original text so that you can ctrl+f it.

Factoid is an app that helps authors capture the biology in their papers into an unambiguous digital format at the time of publication. This tour shows you how to use the app, from beginning to end.

Suggestion: Factoid is an editor that helps represent biological entities in a digital format that can be supplemented to publications. This tour shows you how to use the app, from beginning to end.

An entity is a physical thing, such as a protein. To add one, start by clicking the circle icon.

Suggestion: An entity is a physical thing, such as a protein or chemical. To add one, start by clicking the circle icon.

(1) An interaction is a relationship, e.g. phosphorylation, between two entities. Here's one entity. (2) Here's another entity.

Suggestion:

• An interaction is a relationship, e.g. phosphorylation, between two entities. In this case: here's a protein (Aspartate aminotransferase).
• (2) And here's a chemical (acetylsalicylic Acid).

Click submit when you're done. Once you've confirmed your submission, it will be sent so that it can be distributed by your publisher.

Suggestion: Click submit when you're done. Once you've confirmed your submission, it will be sent so that it can be reviewed and if applicable, distributed with your publication.

Prepopulation : Your paper

Suggestion: Prepopulation : Your figure

Empty textmining result: Factoid wasn't able to find any entities or interactions for your paper. You'll have to add them yourself.

Suggestion: Factoid wasn't able to find entities or interactions for you from the submitted text. No worries: it won't take you long to create your figure.

Non-empty textmining result: Factoid guessed that these entities and interactions are in your paper.

Suggestion: Factoid guessed that these entities and interactions are in your figure.

Edit the entities and interactions until you are satisfied with them for publication.

Suggestion: Edit the entities and interactions until you are satisfied with them for submission.

Factoid couldn't find entities and interactions for your paper, so you'll have to add them yourself.

Suggestion: Factoid wasn't able to automatically find entities and interactions for you from the submitted text. You can create them manually in a snap.

Factoid was able to guess some entities and interactions for your paper. You'll have to amend the document to make sure that it's correct and complete.

Suggestion: Factoid extracted some entities and interactions from the submitted text. You can validate the information and complete the figure if something is missing.

[maxkfranz]

Superseded by the video