#156 Help documentation notes

Feature
open
mikeu
5
2013-03-16
2010-02-27
David Benn
No

This tracker is a place to collect notes regarding help documentation.

Discussion

  • David Benn

    David Benn - 2010-02-27

    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)

     
  • David Benn

    David Benn - 2010-02-27

    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?
    Bayer, ...?

    Note that this is a function of the VSX inegration.

     
  • David Benn

    David Benn - 2010-04-08

    It was suggested at the NACAA 2010 workshop that the means curve calculation methods used in VStar should be documented.

     
  • David Benn

    David Benn - 2010-07-08

    I'm not sure why I mentioned Bayer below... It's the Harvard Designation.

     
  • David Benn

    David Benn - 2011-04-10

    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.

     
  • mikeu

    mikeu - 2011-07-23

    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.

     
  • David Benn

    David Benn - 2011-07-24

    Thanks for reporting this Mike! I've fixed the broken link in:

    http://vstar.svn.sourceforge.net/viewvc/vstar?view=revision&revision=785

    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?

     
  • mikeu

    mikeu - 2011-07-24

    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.

     
  • David Benn

    David Benn - 2011-07-25

    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.

     
  • mikeu

    mikeu - 2011-07-25

    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.

     
  • David Benn

    David Benn - 2011-07-27

    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.

     
  • mikeu

    mikeu - 2011-07-31

    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.

     
  • David Benn

    David Benn - 2011-07-31

    Agreed re: min size.

     
  • David Benn

    David Benn - 2013-03-16
    • milestone: Feature_-Phase_1 --> Feature-_Phase_2
     

Log in to post a comment.