[kde-doc-english] Fwd: [Quanta] Quanta Documentation: English

[Jeffrey Sabarese]

Forwarded per Philip's request, sans attachment:
-js

---------- Forwarded message ----------
From: Jeffrey Sabarese <core5fedora at gmail.com>
Date: Feb 4, 2007 12:58 AM
Subject: Re: [Quanta] Quanta Documentation: English
To: quanta-devel at kde.org
Cc: kde-doc-english at kde.org, philip.rodrigues at lincoln.ox.ac.uk


Hi there! Let me first say that it's an honor and a privilege to have
the opportunity to communicate with you on this level, gentlemen. :)
The amount of respect that i have for your collective genius, i cannot
put into words. I want you to know, also, that I very much appreciate
the amount of time spent by you in the development of the software.
You will not receive complaints from me. :wink: ... questions, or
perhaps "wish-list" ideas, but never a complaint. (not that it was at
issue).

I came to the desire to "help with" the Quanta+ documentation from
simply reading it-- as Andras cited, and finding some text to be
"simple describing", or even not quite a fair description-- or perhaps
in "poor English".  Having studied English, and finding joy in writing
"tutorial" or "documentation" styles of text, I decided to offer
myself as available, and eager to help, if welcomed. I began
communicating with Philip Rodriguez and Andras regarding the best
approach to consuming the existing documentation, locating any
deficit, and then adding, revising, etc.. Both Philip and Andras have
been extraordinarily helpful.

Please note the attachment containing three screen-captures. According
to what I've learned from Philip and Andras about the "trunk" and the
"branch", where i should begin, etc.-- the contents of the SVN which i
received doesn't seem consistent with what i've understood. This
continues to present difficulty to me in my understanding of precisely
where to begin.

It's probably a matter of first-time fumbles, but unfortunately I need
clarification about the contents of the SVN (as shown in the
screencaps). What i've recorded via screen-capture is what "came down"
as the SVN, as illustrated in the image showing the Terminal output.

On 2/2/07, Mark A. Taff <marktaff at comcast.net> wrote:
>  most quality written works are heavily edited and reworked until a
> quality result is achieved. I think for a lot of documentation the first
> draft is the *final* draft.

This is one of the issues that, in making myself available to you, and
in working as much as i am able on my own, I hope to be able to help
create a "final" draft more becoming of the Quality of Software which
is Quanta Plus. The existing docs are considerable, and vast-- but I
hope to be able to improve upon it-- however small or significant my
contribution. I believe the key to a successful documentation is a
structured focus on the End User, as Andras has also stated. In a
perfect world, it would be nice to have even some "Camtasia Studio"
flavoured tutorials to supplement the text-- pages perfectly balanced
with accuracy, detail, and brevity-- beautifully styled pages, robust
with images, attractive fonts, example projects, etc. Realistically,
perhaps it might not make it to that point over-night, but I'd like to
maintain that sort of vision (the animation is probably a bit "much",
but hopefully you get what i'm trying to say...)


> 2) A developer writing documentation can go by what they remember and how
>  things were intended to work. Someone else has to go through a process of
> exploration based upon thumbnail information from developers. In this process
> there is also exploration and enhanced confirmation of operation as well as
> feedback to the developer. This can uncover critical bugs and UI issues.

I agree w/ Eric's point here (and also, his points 1 & 3...).
I'll close my long-winded text by reiterating that I hope to be able
to contribute in whatever way is most appropriate and helpful. I have
no desire to "overstep my bounds", to stomp all over existing text, or
inconvenience the development team with micro-manageable questions.
There will be times, in accordance with "point #2" of Eric L's text
above, where I will likely seek your input and guidance. That said,
I'd like to know what is your (the collective "your") preferred method
for me to pose inquiry? what would YOU like to see me do with this?
how do you want me to "come at you with this"? what do you want to see
from me, and what do you NOT want to see from me?
(please feel free to answer any / all / none of those closing questions. ;)

respectfully,
--Jeffrey Sabarese

(please see attached)

PS. believe it or not, i can be concise but i felt as if this was my
first real "introduction", hence the somewhat extended version.



-- 
/* ************************************************ */
     Quanta+ Web Development IDE:
       http://quanta.kdewebdev.org/
      Quanta+ Wiki:
        http://tinyurl.com/3dzqxk
      Other Quanta Tips:
        http://invisiblepixels.org/progs/quanta.html
/* ************************************************ */