User manual: add visual resources

[ThomasLohnert]

Polaris expressed that even with the user manual as a crutch, some of the more complex dialogues in the IBEX GUI can be a bit daunting. As a Polaris instrument scientist, I would like the user manual to contain visual media to support the guides for common IBEX interactions, e.g. in the form of screenshots showing the interface at various steps, or video walkthroughs of common processes. Creating the latter may actually be less effort and provide more insight to the user.

[kjwoodsISIS]

If we include screenshots in the manual, then if we change a dialog at some point in the future we also have to remember to update the manual at the same time - otherwise the manual starts to get out-of-date very quickly. the same could also be true of video walkthroughs, although, if they are easier to create, it might not be such a burden. We should ask the POLARIS team (and other scientists) which dialogs users find daunting. It may that we could improve the text in the manual itself.

[ThomasLohnert]

That is true, but if we make changes to the interface that are substantial enough to warrant updating the screengrabs, would we not have to update the user manual in those cases regardless? I personally think the increased value of the manual to the user would be worth the slight overhead. Producing an updated screengrab and adding it to the manual should be a matter of minutes.

I think asking the scientists which bits of the GUI they find confusing is a good idea regardless though, I will send a message to the Polaris team to start with.

[John-Holt-Tessella]

If we do this we should look at the possibility of automating the collection of screen shots/videos.

I feel that the manual should be small most of the functionality should be obvious. The manual should contain a broad outline of the system. The rest should be sign posted in the GUI.

[ChrisM-S]

As a pointer, I agree with @John-Holt-Tessella the manual should be small and ideally should not need much explanation for the GUI or using IBEX. Two things I can think of which are needed which will determine the actual size:

1. Documentation of the underlying method/technology and how to run the control system e.g.

   • What is an alarm, when would you use it
   • Difference between a setpoint and a reading.
   • How to see/understand Blocks size will be determined by the complexity of the control system we expect the general user to need to understand to do an experiment. The more complex, the more manual we will need.

2. Documentation of workarounds, known inadequacies in the user interface

   • possibly some substitute for online help which is missing (or which might be provided by an "F1" or help button style pop-up of the manual).
   • something which has to be done outside of the GUI
   • or on the command line and there is not sufficient command line help size here we should be able to keep reducing in the manual as the GUI takes up the load of providing context sensitive help. The better the user experience on the screen, the less we need in the manual.

Ideally, I think pictures could be very beneficial in (1) some screenshots would be useful to allow recognition of what an alarm might look like when active/inactive or to show a setpoint/readback plot. In (2) we should avoid as far as possible explaining things (in text or menu clips) which are down to issues in the interface.

[ThomasLohnert]

Notes from a meeting we had with Russell Ewings today:

• The audience for this is split in 3 parts with different needs:
  • Users: Need an introduction to the main features of IBEX (How to find and control devices, scripting, starting/stopping runs, ...)
  • Instrument Scientists new to IBEX: Need to know more advanced tasks, e.g. how to set up configurations
  • Experienced Instrument Scientists: May need help with complex and specialist tasks - perhaps less suited for pre-made video tutorials.
• Generally, videos should be kept short and focused
  • This helps avoid people having to skip through lots of material to find the bit of information that they want if they are using the manual as a lookup tool
  • This will reduce the amount of material that has to be re-recorded after a change in the client
  • Taking this to an extreme, we have discussed the option of creating animated gifs rather than full video tutorials, which could result in more of a "visually enhanced user manual" rather than distinct training videos
• Russell suggested group-specific pages to cater to different user needs.

The next steps are as follows:

• Russell will gather some more information from scientists how they use the manual to help shape clearer requirements
• Russell will get IBEX developers invited at the start of an experiment so we can shadow some new users receiving an introduction to IBEX from the instrument scientists
• Meanwhile, we will investigate different screen capture tools, and select an appropriate section of the manual (e.g. "how to start and stop runs") for which we will create one or several different video-supported demo versions, which we can then show to scientists to gather feedback on different approaches.