This tracker is a place to collect notes regarding help documentation.
It seems clear that we will need to completely change the approach to Help docs.
Reference to closed "usability of Help Contents..." tracker: https://sourceforge.net/tracker/?func=detail&aid=2898529&group_id=263306&atid=1152052
From this tracker https://sourceforge.net/tracker/?func=detail&aid=2902839&group_id=263306&atid=1152052:
There is currently no way to access the ChangeLog or ReadMe from within the
VStar interface. Although we are including these text files on the aavso
server as part of the WebStart deployment they do not get downloaded to the
client computer. (except for the ReadMe within the ./images directory
which is within the .jar but not readable through the UI)
From this tracker:
Document what kinds of names can be used in dbase-new-star
What kinds of names can be entered into new-star-from-database dialog?
Note that this is a function of the VSX inegration.
From another tracker https://sourceforge.net/tracker/?func=detail&aid=2913565&group_id=263306&atid=1152052:
VStar uses various acronyms and terms (in dialogs, charts etc) that it
would be beneficial (especially to new or inexperienced users) to add to
Brought help HTML doc up to date with where we are at in http://vstar.svn.sourceforge.net/viewvc/vstar?view=rev&revision=463
It was suggested at the NACAA 2010 workshop that the means curve calculation methods used in VStar should be documented.
From https://sourceforge.net/tracker/index.php?func=detail&aid=2983683&group_id=263306&atid=1152052: Maybe in the help somewhere, we can state that a CCD-derived magnitude is "untransformed" unless otherwise stated.
I'm not sure why I mentioned Bayer below... It's the Harvard Designation.
Here's a reasonable page about JavaHelp:
The Fortran TS docs (e.g. file:///Users/david/aavso/prgs/ts/ts_g77.htm) re: period analysis should be adapted for VStar's Help docs.
In "Help Contents..." the link to "AAVSO download format" is broken. Clicking on the link open a popup with the url http://www.aavso.org/data-download/downloadformat.shtml and yes/no buttons. I can't find the link where this info now resides on the aavso.org website.
Thanks for reporting this Mike! I've fixed the broken link in:
Given the poor user experience one gets with the existing Help window, I am thinking of making use of the Java 6 Desktop API to open the help page in the default browser. If that fails for whatever reason, then I can still make it fall back to the existing window. Thoughts?
The existing popup help window is fine for basic info or reading the license, but clicking on the citizen sky website link brings up a mangled version of the page. It is really not suited for rich content, and the lack of navigation (how do I go back to the previous page I was reading?) is troublesome. I'd say that to use the user's default browser to render help is better.
Agreed. What I may do instead is add a Help menu item that opens the user's browser (if possible) to take them to the online VStar page. For the simpler help doc, I may remove all links and possibly move away from HTML. The rich text editor widget in Swing understands RTF, so we could create an Open Office / Word doc that can be saved in multiple formats like RTF and PDF.
Added online docs link to Help menu where platform supports the Java 1.6 Desktop API in http://vstar.svn.sourceforge.net/viewvc/vstar?view=revision&revision=786
Having a those two options for help sounds good. There are a couple of things to keep in mind about help regarding how people might use vstar.
Some might want to run vstar on a laptop at a remote dark sky site with no net connection and then read data files and help from the local hard drive. So there needs to be something included in the install that gives the basic info that they need without requiring the network.
Second, someone might have an earlier version of vstar and then click on the link to online help which documents features only found in a later version.
So we need to think about what content is critical to have as a reference if you need to run vstar offline. The second issue gets a little more complicated. I can think of a few ways to handle that, but I'm not sure which is best.
All good observations, thanks Mike.
For the plugin development document, I created a PDF. We could take the same approach with the normal Help doc.
When you download a distribution zip from SourceForge, docs can be bundled with that for standalone VStar use. Aside: I added vstar.sh and vstar.bat (the latter untested) recently in order to be able to run VStar with the same JVM params as with JNLP. I have also considered creating an installer.
A couple of random and mostly unrelated notes:
* We should rewrite the minimum required and recommended specs for running vstar. The vstar popup help still lists the Sun Java Look and Feel Graphics Repository, for example, which is no longer required.
* Another is recommended screen size. Vstar works fine on a tiny netbook with 8" screen but you need about 720 pixels high minimum to be able to see the entire plot without a scroll bar. Vstar does not break on small screens, but it is more difficult to use.
Replaced incorrect reference in Help HTML to Look & Feel repository with a references to Nico's icons jar (reported by Mike U).
Agreed re: min size.
Log in to post a comment.