Issues with committing docs (was Re: [kde-doc-english] kdepim/doc/korganizer)

[Lauri Watts]

On Tuesday 27 April 2004 00.53, Jürgen Nagel wrote:
> Am Donnerstag, 22. April 2004 15:03 schrieben Sie:
> > CVS commit by lauri:
> >
> > Huge patch from Tom Albers, with much thanks!
> >
> > CCMAIL:kde-doc-english at kde.org
> > CCMAIL:toma at kovoks.nl
> >
> >
> >   M +210 -345  index.docbook   1.34
>
> Hi Lauri,
>
> I was a bit confused when I saw that commit to the KOrganizer
> documentation, since I too was at integrating the patch from Tom Albers
> combined with adding own stuff.

I reposted it from i18n to the right list for comment, but got none, gave it a 
quick once over myself and committed it.  Please accept my apologies, it 
totally slipped my mind that KOrganizer now has an actual maintainer to care 
for it.  If you're not already on kde-doc-english, I suggest you subscribe 
(it's not that busy.)  

> Due to that it took a bit longer, but now I have an (admittedly) small
> patch with the first set of additions to give you a preview.
>
> Do you commit the changes if they meet the quality standards or should I do
> it from now on?

It's up to you.  Phil or I commit most patches, but it's mostly because few 
authors have cvs accounts, and it's not worth the admin time setting them up 
with one for a one time contribution to a single doc (which, if we're honest, 
is what most people come up with.)  Anyone who sticks around a couple of 
versions, or submits work on several docs, we usually get them a CVS account 
anyway.  Since you already have an account, and experience with the markup, 
if you're happy to commit your own work, that's fine by me.

There are some things to consider when committing documentation, that are a 
little different to working on source code (and to explain why we're a little 
careful about committing things.)

1: Translation - in the GUI, a single message left untranslated, is a single 
message left untranslated.  In the docs, a single message left untranslated 
effectively removes the entire *file* - it won't be regenerated in the target 
language until the *file* is 100% translated.   Which means, we try not to go 
back over existing content too often, and is also one of the reasons it's 
useful to break things up into separate files.  It's pretty hard for the 
translators to get the whole file up to 100% if it's getting constantly 
changed.

2: Merging - CVS is fine for merging on a line by line basis, not so hot with 
a largely paragraph based format like documentation.    This makes it lots of 
work to deal with if you're writing and someone else edits the same content.   

This is also one of the major reason we use minimal (ie, no) formatting in the 
source.  Unlike line-by-line source code, it *does* matter, and can make big 
diff's virtually impossible to deal with.  So don't indent, try to be 
consistent with wrapping at column 76ish, and feel free to use newlines and 
blank lines to organise the source, it helps minimise the impact.  A second 
reason is that some elements are rendered verbatim, so if you indent them in 
the source, they'll be indented in the HTML rendering, which usually results 
in them running around the right hand side and wrapping badly (and looking 
really ugly.) 

Regards,
-- 
Lauri Watts
KDE Documentation: http://i18n.kde.org/doc/
KDE on FreeBSD: http://freebsd.kde.org/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: signature
Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20040427/742a9d81/attachment.sig