Documentation - workflow and deployment [was: Export Kexi documentation]

[Jaroslaw Staniek]

On 23 October 2011 15:06, C. Boemann <cbo at boemann.dk> wrote:
> On Sunday 23 October 2011 13:51:45 Yuri Chornoivan wrote:
>> 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.

+1 from me, freezing documentation work is another obstacle added to
already hard deployment of our apps compared to "web apps". OTOH it's
thanks for exceptional dedication of our Doc Team that people without
online access can still experience the documentation resources. These
are always snapshots however, and in ideal world existence of the
offline option should not affect our workflow.

Moreover I was never convinced the 'noarch' packages for translations
and documentation should be packaged in distribution-dependent format.
Independent packaging is the ultimate goal I would look for. On Linux,
Windows, maybe also tablets. +1 for GHNS option then: this would let
us escape from the packaging fragmentation (or maybe there are already
docs deployed this way?)

-- 
regards / pozdrawiam, Jaroslaw Staniek
 http://www.linkedin.com/in/jstaniek
 Kexi & Calligra (kexi-project.org, identi.ca/kexi, calligra-suite.org)
 KDE Software Development Platform on MS Windows (windows.kde.org)