Open ThomasLohnert opened 6 years ago
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.
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.
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.
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:
Documentation of the underlying method/technology and how to run the control system e.g.
Documentation of workarounds, known inadequacies in the user interface
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.
Notes from a meeting we had with Russell Ewings today:
The next steps are as follows:
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.