Export Kexi documentation from userbase to docbook

[C. Boemann]

On Sunday 23 October 2011 13:51:45 Yuri Chornoivan wrote:
> написане Sun, 23 Oct 2011 00:40:59 +0300, Jaroslaw Staniek
> 
> <staniek at kde.org>:
> > I have one rather general question, do you think updates to the
> > documentation have to be synchronized with Calligra/Kexi releases?
> > Even if there's change and no release for an app, project members
> > would want to extend documentation with bits they planned but just not
> > made it for the release for whatever reason.
> > 
> > I think both Calligra developers and members of the Documentation
> > Team(s) could express their opinion on this one.
> > I particularly would see liberal approach for documentation release
> > schedules as nice but also can accept the rule when online
> > documentation is ahead of the offline one.
> > And I am assuming there is no concept of freezing periods for online
> > documentation, but only expectation that it should be always made in
> > "stable/clean" state each time the Doc Team grabs the content for
> > offline releases.
> > 
> > Would be great to note down see some such rules that we're collecting,
> > as "official" - if there is anything missing.
> 
> Hi,
> 
> For me, as a translator it would be good to follow KDE schedules:
> 
> 1. Documentation export to master 14 days after hard feature freeze.
> 2. Documentation export to branch right after minor release (there should
> be some agreement on not including documentation for new features into
> branch releases). master/branch separation can be done by the different
> page list (separate pages for new features on UserBase). If separation
> cannot be done, then we need some other rules (special tags for versions
> or something else).

Hi

I'd like to question how good it is to move the  documentation back to master 
/ branch. And even the wider aspect of how documentation should be handled.

Here is a time line of how things happen. And I don't think it's realistic to 
change that:

1) The coders and user interface designers create a new feature or change some 
old behavior in the application

2) The string translators almost immediately translate new ui visible strings

3) The application is released.

4) The documentation writers, who we hope are dedicated users, write how to 
use the new or changed features. Being a crowd sourcing thing the 
documentation writers can't and shouldn't be expected to do this before 
release.

5) The documentation translators have their chance to translate the 
documentation


So my suggestion is that the translated documentation is on a locked website 
and for the translators to upload to whenever they like (It can never be too 
soon as the documentation itself is also never too soon). This means that 
there is never a release date for documentation. The English documentation is 
constantly being worked on and the translations keep up as best they can.

If the translators would like to work on docbook all that is needed is to 
constantly create new docbook editions of userbase, store that on some git or 
svn somewhere, translate that and put it on the locked website.

Only valid reason for having documentation released is for those users that 
can't be online whenever their computer is on. This is a valid point, but I 
really think we should have some kind of GHNS for this, and not ship outdated 
documentation. Some distributions may choose to ship cached versions of the 
documentation (which the user can update whenever online). but it should never 
ever be part of the application release itself.

Just my two cents worth