[Kst] Documentation

[Barth Netterfield]

On December 20, 2004 05:34 pm, George Staikos wrote:
> On Monday 20 December 2004 13:04, Philip Rodrigues wrote:
> > Hi all,
> > I've been contracted by George to work on the Kst documentation. I'm just
> > starting out, and finding my way around, so I'm looking for some feedback
> > about what I should be working on.

Welcome!
> > ......

> > Manpage: Since Kst has a command-line 'mode', it might be appropriate to
> > have a manpage. The necessary content appears to exist in the docs, it's
> > just a case of making it into manpage format (hopefully autogenerated).
>
>    Also a good idea.  Barth, what do you think?  High or low priority on
> this?

Important.

> > Technical level: This is perhaps the one on which I would most value your
> > input. The current level of the Kst docs appears to assume a fairly high
> > level of technical knowledge on the part of the reader. As I understand
> > it, the current user base is research scientists, so this is appropriate.
> > Is it intended or desired that the docs reduce their technical level, or
> > should they stay as they are in this respect?
>
>    No, I don't think they should be less technical.  In some ways, we might
> want more technical details such as real-science applications of Kst as
> examples.

I could imagine that science highschool or university undergraduate students 
could find kst useful for their homework (I know when I was 16, I dreamed of 
a program like kst...)  So having an example somewhere of how to plot some 
data from a notebook and fit a line to it could be cool.  But I think that 
would be the least techinical level which would ever find kst interesting.

> > Intro/Overview of the doc: I'd like to add an introductory section with a
> > brief overview of what the documentation contains, to help users find the
> > appropriate section. Any thoughts?
>
>    Good idea.
>
> > Examples: The discussion in the existing docs is often quite abstract.
> > Would it be useful (I think it would) to add some practical examples (eg,
> > "Making a color map" or "Generating a power spectrum") that walk through
> > some common tasks in Kst?
>
>     Exactly, as I mentioned above. :-)  I think this is very important.

agreed.  There exists a tutorial, which is in CVS but not linked to the docs 
anywhere (!) which should be enhanced/replaced, and connected to the docbook.

Right now, the UI for 'Making a color map' is woefully inadequate, and 
probably shouldn't be documented more until we finish it.  Which we haven't 
yet decided how to do.

There are some changes which have happened since 0.99, which is the release 
the docs are up to date for.

eg: 
-psd's equations, and histograms are no longer curves.  They just export 
vectors, which the UI makes into curves.
-The "export to graphics file" dialog has changed significantly.
-New features have been added to printing and the plot dialog.

Perhaps re-making the screen shots will uncover most of these changes.

cbn