On Thu, 5 Jun 2003, Malcolm J. Currie wrote:
> > > 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.
I must admit I had been thinking about the java stuff as pretty much
separate from the rest of the starlink system, and hadn't been
thinking in terms of SUNs. I suppose this is largely because
showme/findme are quite platform specific, and latex/star2html
doesn't seem like a very java-friendly technology. Such documentation
as there is ought to be available within the tool itself, and
star2htmlized SUNs as such look quite ugly within the sort of
smallish help window that you get in TOPCAT and, in particular,
Treeview. Paper documents need screenshots to make them comprehensible,
but these can be a bit of a waste of space in an in-tool help screen.
Moreover, trying to automatically generate these things
from LaTeX originals as part of the ant-based build process is
probably a bad idea.
Another issue is that if we're producing stuff with small incremental
changes and releasing between CDs it becomes a very time-consuming
job to keep screenshots in paper documents up to date with the current
layout of the tool itself. The layouts of windows, pixmaps
on buttons, tools in the toolbar etc are changing daily in TOPCAT.
Steve, was SUNs what you had in mind? If so, and if you can give
me a couple of days, I can update the treeview one and knock one
up for TOPCAT. These will be separate from the online docs in
the applications though. We'll have to decide at some point
whether they stay small, get updated in parallel with the online
docs, or get somehow automatically generated from a single source.
Yes, I know that XML is/could be the answer somewhere along the line,
but on the timescale of this CD we don't have time to fix up a
working system, at least not under platform-independent ant control.
> 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.
At that close-to-the-metal GUI level it's hard to document since
exactly what you have to do with your mice etc is a function of
the behaviour of the platform (OS/window manager) and is not in
principle knowable by the application.
> If you're not offering documentation outside TOPCAT itself, the first
> widget to appear should have a Help option.
Yes I know it should. It doesn't. The deadline has passed.
If I had more time, it would be possible to address this.
Mark
--
Mark Taylor Starlink Programmer Physics, Bristol University, UK
[log in to unmask] 0117 928 8776 http://www.star.bris.ac.uk/~mbt/
|