[kde-doc-english] First Docbook Submission

[Jeffrey Sabarese]

Hi Philip, thanks for your reply! (so quickly! :)

i wanted to respond to a couple of your comments, and also send this
to both lists. i think that should bring everyone up to speed as i
didn't mail the kde-doc-english address previously...

On 2/25/07, Philip Rodrigues <philip.rodrigues at lincoln.ox.ac.uk> wrote:
> >
> In terms of how to show your changes, the easiest and most usual way is to
> just edit the file you're working on, and then use the features of svn to
> produce a patch, or "diff". This is just a file that contains a description
> of the changes you've made to the file.
>
> Let's say you've been working on a file index.docbook, then you can use the
> following command to create a diff showing your changes:
> svn diff index.docbook
> This command on its own will just display the differences on your screen. To
> save it to a file that you can attach to an email, use:
> svn diff index.docbook > index.docbook.diff

cool. i can do that, no problem. i'm sure it's more efficient than
trying to determine such changes w/ the naked eye. ;)

i want to ensure that we're as "on the same page" as possible, as
quickly as possible, so i can start producing quality, usable results
as soon as possible. so please bear with as i get on my feet with
this. once i get going w/ it-- i won't provide any more sidebar
commentary. i know it gets long-winded fast. sorry 'bout that.

Going back to Andras's first recommendations, i recall he said i could
just write something in an email and send to kde-doc-english at kde.org--
just for getting started, etc. and i was planning to do it that way
for weeks (months!), but i found myself "stuck"-- with such a vast
landscape of possible "contributions" to the Quanta docs--
furthermore, i think it would be best if i work closely w/ those of
you who have a better sensibility of what is and isn't good about the
existing text-.

working with the existing docs, i'm working with structure. to get a
feel for the docbook syntax, and to build upon the existing as a way
of gaining some momentum.
i thought to just go and try to come up w/ something "original" might
be a waste of time (not a complete waste maybe, but in the end,
perhaps).

not to discount Philip's early feedback-- including his instruction to
create the .diff file. -- it's an important "first-things-first" -- so
i'll know to do that, but what else can be taken from how i approached
that first little bit (which can be seen at:
http://centrewebdesign.net/tempshare/quantadocbk/introduction.jeff.docbook
)? Philip thought that perhaps i shouldn't touch the existing stuff--
but i got the impression from the kde-devel list a few weeks ago that
maybe the existing is the best starting point.

the comment i remember which seemed to make the most sense was that
about Developers and Docbook Authors perhaps shouldn't be one and the
same person-- that there should be an ongoing communication between
the two, as a means to arrive at a document which represents both the
technical needs of a good manual, and also the ergonomic.

i believe this duality is critical to good documentation, and i'm
willing to work toward that end with as much effort as i'm able, time
permitting. i hope that we can develop the best means toward that goal
as well. please feel free to tell me when / if you "hate" something,
or vice versa-- and to point me when i'm in need of direction.

i question: which part of the stone should i begin chipping away most
fervently? i want to be confident that what i'm doing is best for the
team, and for Quanta Plus of course. :)

finally: the "docbook syntax"-- i believe it would be more efficient,
yet i don't want to create more work for someone down the line by
coding it improperly. it doesn't look like rocket-science, so i'm cool
w/ going for it-- just let me know when i fumble it so i can nip it in
the bud. recommendations are welcomed.

like i mentioned when i presented the URL a few days ago, i would like
to continue working my way through the existing docs, providing
updates (as .diff files) as i go along. i'll be working with
structure, you all will know what to expect, and then we can expand on
it as necessary. i believe this will be the best approach for me-- if
for no other reason than it will force me to become most familiar with
what is already there. any sections which can be skipped, just let me
know, etc. one step at a time, under that structure, and steady
progress will be inevitable. :)

as always, i welcome your feedback.
thanks!
-Jeff Sabarese

>
> In terms of whether to submit changes to existing wording, or just new
> content, that depends on what the quanta folks say. In general, we tend to
> leave existing text as it is, in order to prioritize making new content. But
> individual teams might prefer something else.
>
> > 2.) Contining progress:
> >   a.)  mindful of dial-up connectivity, may i proceed as i have with
> > this first submission, uploading to my server, then reporting its
> > availability to quanta-devel at kde.org?
> >   b.) if no to "a", then what is the preferred method / location for
> > future submissions? (previously there was a problem w/ an attachment.
> > hence this inquiry)
>
> The current method seems fine.
>
> > 3.) future submissions will be devoid of commentary. i am well aware
> > that i have a problem w/ being concise. and i realize the value of
> > others' time. i apologize to Andras, for i mistakenly overlooked his
> > request that i not send to his personal address.
>
> That's alright :-). It takes a while to get used to the "style" used in
> KDE-related email discussions, and people will cut you some slack :-). About
> sending mail to individuals, we generally prefer mailing lists just because
> it means more people available to answer your questions, and helps prevent
> problems like me disappearing for a week. So you might prefer to send your
> contributions to kde-doc-english at kde.org - there are a number of people there
> who will be able to pick things up if I'm not around, and I read that list
> anyway, so there's no loss.
>
> Regards,
> Philip
>
>


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