[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-i18n-doc
Subject:    Re: [RFC] Documentation, take 2
From:       Lauri Watts <lauri () kde ! org>
Date:       2005-12-07 22:03:58
Message-ID: 200512072303.59346.lauri () kde ! org
[Download RAW message or body]

On Wednesday 07 December 2005 22:04, Nicolas Goutte wrote:
> On Wednesday 07 December 2005 21:09, Lauri Watts wrote:
> > On Wednesday 07 December 2005 20:05, Nicolas Goutte wrote:
> > > > In the interim, I am going to start committing updates and
> > > > corrections to trunk over the weekend, unless I hear a very good
> > > > reason to not do so.  I have at this point no reason to believe most
> > > > of the applications we are talking about have or even will see any
> > > > major gui redesign at this point. KPDF in KDE 4 is currently, and for
> > > > the forseeable future, looking very like KPDF in KDE 3.5, and this
> > > > will allow us to at least point to docs.kde.org for updated
> > > > documentation for many applications.
> > >
> > > May I suggest instead that you create a branch in branches/work like
> > > branches/work/freshdoc (or a better name) and that you copy (with svn
> > > copy) there the doc directories of modules that you need (similar to
> > > what is done for l10n/documentation but not with external references):
> > > branches/KDE/3.5/kdelibs/doc to branches/work/freshdoc/kdelibs
> > > branches/KDE/3.5/kdebase/doc to branches/work/freshdoc/kdebase and so
> > > on...
> >
> > I think this is an overly complex way to solve a problem we don't
> > actually have (to wit, people writing docs for 4.x already).    By the
> > time people are ready to work on 4.x docs, we can simply declare
> > moratorium on updates for 3.5, and grandfather them out of trunk.
>
> I have just wanted to propose a clean way of doing, in the spirit of
> Subversion.
>
> Whatever you choose this way or to commit in KDE4's source, you will not
> get any translations in the current state. (Scripty does not merge in
> trunk/l10n for the main KDE modules).

Heh, I guess we had a communication breakdown, but I thought that was the 
entire point :)

We can do this without disturbing l10n, and still making it quite simple for 
those teams that do wish to backport (just as there have always been some 
teams that are backporting.)

Scripty would also not merge another branch, but I'd have to keep three 
checked out, merged, we'd still have to modify scripty and the template 
generation, so it's not going to save anything there.

If in a few months time, when momentum has really moved to 4.x, it's stable 
enough people can run it (you can't document something you can't run).  We 
can take a look every month or so, and see how things are shaping up, we can 
mark specific documents that shouldn't be backported (for a start there's a 
DTD version change coming up, it'll be very simple to determine which are 4.x 
targeted and which are 3.x targeted once that happens.)

> > > So you will have a clean set of documentation, without any possibility
> > > of mixing up with KDE4. Whoever wants to write documentation for KDE
> > > 3.5.x could use it without delay. You could start right now, not
> > > waiting that this discussion arrives somewhere at a "secure harbour"
> > > (i.e. finding a good solution, agreed by most). Then we would have
> > > agreed on something, the new documenation would already be prepared and
> > > ready. (So the time of the discussion would not be lost.)

Look at it this way.  If there *was* a 3.6, we'd *still* be putting all these 
updates into trunk, and there'd still be a ton of applications getting gui 
changes (more or less cosmetic) leading to occasional mismatches between docs 
and GUI. 

The absolute worst case here is some of the docs may have to say:  "BTW, this 
feature maybe isn't implemented in the version you have, but it's in the next 
version coming up" rather than apps being released with features that users 
don't understand and can't use, because they aren't explained anywhere.

Regards,
-- 
Lauri Watts
KDE Documentation: http://docs.kde.org
KDE on FreeBSD: http://freebsd.kde.org
[prev in list] [next in list] [prev in thread] [next in thread]