> > 12. Documentation, SUN/XXX docs - should the treeview and splat SUN docs now
> > go in the docs package, have they been updated? Are they in the CVS? Only
> > javadocs for classes and other java packages in starjava/docs/ dir when the
> > install target is used. export_full_docs does not give the same output for
> > the javadocs as the install target? We could do with some simple (two pages)

The important thing is that showme, findme, and the software indexes can
access these documents. I do sometimes look at the source in
/star/docs expecting all documnts to be there, but that's a lesser
concern.

It was policy in Starlink not to release software without an
accompanying SUN, which could be referenced and indexed, even if it just
comprised a page outinling what the software was for and did, and a
reference to the full documentation in a MUD or on the web or some other
specified file. So for something like Treeview, if a full SUN isn't
possible right now, there should be a minimal SUN which gives startup
instructions, how to find help, and a link to the full documentation.

Being old fashioned I like a document on paper, especially when
embarking on something new. Online documentation is usually fine to
check on a particular point or reference material, but not for
cover-to-cover reading and annotation. I certainly found the SPLAT
manual helpful in that regard, and I hope we will provide comprehensive
documentation for the Java tools. We can't expect a user presented
with the FROG, say, startup command to work out how to use it properly,
let alone get the best from it, without tutorial/cookbook information.

My experience of the online help in several of our GUI tools is that it
is often incomplete and doesn't give the big picture. It's not just
ours---Mirage's was woeful. The documentation should make it clear
what each mouse button does, and when you need to double-click. Once
you've started using a GUI these become second nature, but as a novice
if you don't know the tricks, then you can get stuck or miss many
features.

> TOPCAT documentation is entirely within the application as a JavaHelp
> browser, though the docs exist as HTML files so could with a
> bit of effort be made accessible externally (I may do this on the
> TOPCAT www page). The main problem with this is that the help browser
> is not accessible from the 'load table' dialog, which is what you get if
> you just invoke 'topcat' on its own. It is not that hard, but not
> trivial to fix this, and I didn't have time to do so before the
> deadline this morning.

If you're not offering documentation outside TOPCAT itself, the first
widget to appear should have a Help option.

Malcolm