Update the User's Guide for the 10.0.0 Release

Overview of updates made:

Selection Info:

• Updated images using IGB 10.0.0
• Added an image depicting how to use the Selection Info display
• Added an image with callouts depicting key terms on this page for users
• Added a link to the Selecting Items page of the User's Guide in the Introduction

Restriction Sites:

• Added more details to the "How to map sites" section
• Enlarged pictures in the "Viewing results" section
  Note: I diverted from the task outlined for the ticket a bit here. The pictures being used currently, now that they're enlarged, do a really good job of showing mapped sites. All I would be showing with an updated image is a longer, harder to read list of restriction enzymes.

File Formats:

• Added a row to the table with information about the CRAM file format.
• Fixed several broken links throughout the table.
  Note: We may want to add a section at the bottom of the File Formats page (once we've vetted CRAM usage in IGB a bit more) that explains more about what to do if the exact genome/genome version they need isn't in IGB (e.g., adding a custom genome to IGB or creating a custom quickload or emailing us to add it).

Additionally, I've also updated the following pages:
Create a satellite IGB QuickLoad site for genomes that are already supported in the main IGB QuickLoad site:

• Updated the QuickLoad site links to point to data.bioviz.org
• Added CRAM as a data file option to the Add data files seciton

Sharing data for a custom genome not already part of IGB QuickLoad:

• Updated IGB quickload links to point to data.bioviz.org
• Added mention of CRAM files to the sections "Create annots.xml file listing available annotations and data sets." and "Add annotation files."

About annots.xml:

• Added information about CRAM files/file indexes to the index row of the table.

Question for the reviewer: Would you like the File Formats smoke testing page updated with a CRAM test?

For review: Please glance over each of the pages I've made changes to and confirm that I've updated everything I can. Additionally, please let me know if there are any other spots in the User's Guide that may need updating that I didn't think of. And, with this new release in mind, maybe it's time to go through the smoke testing documentation and update it, especially with the new apps being worked on and the changes made to searching.

Selection Info

• Some of the images are too large. I would recommend making the IGB window smaller so that the fonts are legible. For example: https://wiki.bioviz.org/confluence/download/attachments/852109/AdvancedSearchTab_Callouts2.png?version=1&modificationDate=1711392655175&api=v2
• Some of the callouts blend in with the image. I would recommend where possible to have the callouts "outside" of the IGB image. For example: https://wiki.bioviz.org/confluence/display/igbman/Quick+start
• Might be worth having a specific callout for block number with a short description saying that for gene annotations the block number is the exon number.

Restriction Sites

• May be worth updating this image as it shows the restriction enzymes being loaded across the entire chromosome, but in IGB 10.0.0 this will not work due to an existing bug/limitation.

File Formats

• Looks good.

Create a satellite IGB QuickLoad site for genomes that are already supported in the main IGB QuickLoad site

• Looks good.

Sharing data for a custom genome not already part of IGB QuickLoad:

• Looks good.

About annots.xml

• Looks good.

Thank you for the comments! The images on the Selection Info page were indeed way too big. Here are the changes I made:
Selection Info:

• I reduced the size of those images that were too large. Hopefully they're still readable! I did reduce the stack height of the annotation track to try and make the figure a bit less busy and a bit more easily interpretable.
• I added a callout to one of the images that briefly explained the "block number" property.
• I modified the callouts on the first image so that they did not overlap with the image.

Restriction Sites:

• Updated the second image (showing mapped sites across the entire genome) in IGB 10.0.0. To bypass the existing error that you mentioned, I simply zoomed in all the way on a point in the genome, then zoomed all the way back out and proceeded to map sites as usual.

Let me know what you think!

• The callouts look much better, could probably increase font size a little bit more.
• The IGB images are still a little hard for me to read. On mac the IGB default window size usually works pretty well (might be different on Windows). I've attached some files to either use or compare to.

Default formatting does appear to be a bit different on Windows vs Mac, but hopefully now that I've exited full screen and taken pictures in IGB with the reduced window size, these images should be more readable. I've updated the images on the Selection Info page. Could you take a look and let me know if the images and their callouts are more readable now? If so, I will update the Restriction Sites page in the same way. If not, I might need to wait until I have access to my Mac computer before updating the images any further.

There's place in the IGB Dropbox where you should save any graphic art created for the User's Guides: e.g., original images, powerpoints with call-outs, final images.

See: "IGB User's Guide" Dropbox folder.

All images and text for the User's Guide should follow the Microsoft Manual of Style book. We have several copies in the lab. Paige Kulzer - please get a copy and take one home, leave in the office.

Style example:

• Avoid complex grammar constuctions
• Use present imperative voice (ex) To do a thing, press the button labeled Do It.
• Make sure that the images are clear, i.e., you can read the text at multiple screen resolutions
• A user should not have to click on an image in order to read / understand it

Other guidelines:

If at all possible, when updating existing images, make the new image look like the old one or better (e.g. same width versus height ratio, same wording, same scene, etc.) and also use the same name for the image.

In the dropbox and with names of images, try to give informative, short names to images so that we can more easily understand what they are and what the purpose of creating was.

Selection info images look good. Go ahead and update the Restriction Sites images.

I've updated the images on the Restriction Sites page to match how I updated the Selection Info page previously.

All images used to update these two pages have been saved in Dropbox (e.g., /Users/pkulzer/Dropbox/IGB Users Guide Art and Style Info/SelectionInfo/Images/). I have also compiled the images used for each page into a powerpoint document and placed it in Dropbox along the same file path.

In the future, I will be sure to follow pre-existing naming conventions for images in the User's Guide and will continue to update Dropbox accordingly. I will also match the height/width ratio of images when I'm updating them.

For now, the Restriction Site page is ready for another review!

Images on the Restriction Site page look good.

Closing ticket.