When expanded, Help tab takes too much space in the module view, pushing all module specific functions too far down (see example for Data module). Now that almost all the documentation is online, and modules provide hotlinks to the readthedocs or github repo as oppose to inline documentation, can we truncate this? I think 4-5 lines would suffice.
In general, we cannot fully rely on online documentation (custom applications may not even have any publicly accessible documentation, network is not always available, etc.) but I agree that often the Help area takes more space than necessary from the very precious vertical space.
There is no fixed size set for the Help tab and the the text already displayed using a ctkFittedTextBrowser, but the problem may be that the Help&acknowledegment section size is determined by size of both the Help and Acknowledgement tab content. Instead of trying to fix this problem in isolation, I think it would be better to address the problem of lack of vertical space in the module panel overall.
For example, we replace the current Slicer icon and Help&acknowledgement section:
With a more compact row consisting of Slicer icon, module title, and module actions (show help, show acknowledgment, add module to favorites, undock module panel, hide module panel, …):
or
The Help and Acknowledgment buttons could show the text in a dockable widget, which could be moved out of the main window layout or docked to the side.
This new title widget could replace the module panel title bar, which is the empty row with the small undock and close buttons, saving one more line.
As a quick test, I would recommend trying to hide all the non-essential elements from the module panel - the result is breathtaking:
slicer.util.setApplicationLogoVisible(False)
slicer.util.setModuleHelpSectionVisible(False)
slicer.util.setDataProbeVisible(False)
slicer.util.setModulePanelTitleVisible(False)
We already do that in SlicerMorph, those are our defaults. However, I think there is some sort of a bug with the ctkFittedTextBrowser. When I first open the help, it has a huge blank space. But then when I click on the Acknowledgement it actually collapses that space, and when when I go back to Help, that blank space is removed.
This behavior reproduces for other modules too (e.g., segment editor)…
Unfortunately, these set...Visible functions are only usable for custom applications and testing, because you would need convenient way to show these GUI elements (except the application logo, which I think we should just remove and show it in DataProbe when the mouse pointer is out of the view layout). The module panel title bar might not seem essential, but it is, because without that the module panel cannot be undocked or docked to another location.
The fitted text browser may not actually compute size hints until its first rendered, so maybe the size hint computation should be triggered somehow. Or merge help and acknowledgement into a single browser (how it is done in the module finder). Still it would not solve the main problem that there are just too many things in the module panel, and that if you show something in the Help section then you need to scroll a lot to see the module GUI. That’s why I think a better solution could be to show the help text in a docking widget, outside the module panel (this way the user could read the help text while manipulating the module widget).
There could be of course many other options - it would be great to get more feedback and suggestions.
I think how the documentation is going to be presented will determine how the Help tab should be reconfigured. As is, the sole function of Help is to provide a hotlink to online documentation. If this continues to be the case, I don’t think it will be helpful to have a another docking window as help, you may just as well use the external browser. Help tab might be collapsed into a something a lot more simple to provide the link functionality.
If somehow the online documentations can be rendered inside this Help window close to the fidelity of github, I think a dockable widget makes sense.
But as project we can’t maintain two different documentation sets to cover offline use cases.
A much more important role of module help is locating a module in the module finder. You just type a word and you get a list of modules that mention that word in their help text and you can very quickly browse through dozens of modules, have a quick glance at the few-sentence description of what the module does immediately (instead of waiting for several seconds for a webpage to open). We could make this even more powerful by somehow fetching module help text for all modules in all the extensions.
I agree that it is important not to duplicate module documentation and that hosting it in the same repository as the code makes the most sense (and you can set up readthedocs to handle versioning and offlne access). But keeping this short module description (Help & Acknowledgemen) is not that much duplication and is quite useful.
We just need to figure out what are the best ways to make the information accessible.
I like this idea - it could be the last step of the factory after building all the extensions to compile a file with all the help text fields. Then in the module search we could propose extensions based on keywords.
1 Like
No, that’s totally fine and that’s what we do that anyways. My point is, if all the information that the help and acknowledgement is going to convey continues to be a short summary of the module and a link to documentation, then I am not sure how valuable is to rethink the Help tab as a separate dockable widget. We might perhaps keep as is, and just fix the erroneous auto-resizing issue. But you guys now this better of course.
This sounds great actually…
@muratmaga how do you use the help section now? Is the blank area below the text a cosmetic issue only or it affects functionality as well? Showing the help and acknowledgment text in one widget would probably solve the blank space is but it would make the area bigger. Would this work for you?
We use it very similar to other modules. Provide a short description of what the module does, and provide a link to the documents on GH page.
I wouldn’t say a cosmetic issue. because the extra space in the help tab takes so much of the vertical space (unless one goes back and forth between acknowledgement and help section), we decided to start out views with Help compressed (see below). We tell that Help is there, but it is easy to overlook, if you are not a regular slicer user. Even the reviewers of the SlicerMorph paper missed that.
This is how modules initiate:
versus the same module Help section expanded:
versus auto-resize kicks in
The last would be a good solution. That way parts of the actual module is still visible. And the help tab is expanded.
(As a side note, older modules have large logos and text in acknowledgement section, which end up taking a lot of space, and it is one of the reasons that help section having so much white space. Those logos do not render particularly well, and their layout leaves much to be desired. See Volumes module below:)
Help & Acknowledgement section is collapsed by default. Users can open it, read it, maybe click the link to the online documentation, and then close it if they want to use the module. For the rare case when the help text contain step-by-step instructions then it could be useful to keep it open, but then the user needs to scroll between the instructions and the module GUI anyway (somewhat less if the minimum amount of space is used), but for that a better solution could be a separate docking widget. But from all the discussion above, it seems that keeping the help text as a short summary and link to online documentation (no step-by-step instructions) seems to be a more reasonable option.
Oh, I didn’t know that became default in overall Slicer. Anyways, but that’s really not a good thing to do. Help do contain useful information and starting collapsed make so inconspicuous in the module view that it is over looked.