[Kst] Documentation

[George Staikos]

Welcome Philip.  Sorry I didn't send a message to the list ahead of time.  It 
was about 2 away on my TODO list when you sent yours.  I guess that's 
GMT-500's fault. :-)

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.
>
> I took a look through the existing docs, which appear to be extremely good,
> and very comprehensive. I thought of a few (fairly minor) things on which I
> could spend some time, so I'd like your opinions on whether they're
> needed/desired:
>
> Screenshot format: For official KDE documentation, we've standardized the
> screenshots to the Plastik widget style and window decoration. The existing
> Kst screenshots aren't in this style. Is it a priority for anyone that they
> be changed?

  In any case the screenshots need to be updated at some point because the UI 
has changed.  Using Plastik is a good idea.

> Formulae: Just a technical query: How are the PNG's of formulae generated?
> They look like LaTeX to me, but I'm not sure of the easiest way to get PNG
> output from LaTeX for individual formulae. Could someone point me in the
> right direction?

   I'm not sure how Rick did it, but there are many ways.  KSnapshot for 
instance....  You could also extract it with kpdf.  There might even be some 
tools for conversion from DVI.   

> 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?

> Index: Adding an index using DocBook is fairly easy, and hopefully makes it
> easier for users to find the particular information they're looking for.
> Any thoughts?

  Yes definitely.

> 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.

> 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.

> Hopefully some of those suggestions are useful ones that I can pursue. If
> you have any questions, comments or thoughts, please do get back to me.

   Looks like you're on the right track.

-- 
George Staikos
KDE Developer				http://www.kde.org/
Staikos Computing Services Inc.		http://www.staikos.net/