[scribus-dev] Scribus documentation translations temporarily removed from builds

[Christoph Schäfer]

On Mittwoch, 1. Dezember 2010 01:06:57 Louis Desjardins wrote:
<snip>

My impression is that the discussion is getting a bit out of hand, probably 
due to misunderstandings and people talking past each other.

> >>  Can we turn this into a wikipedia-like way to go? If for some reason
> >> 
> >> someone makes an error and mixes things or deletes some content, we have
> >> ways to return to the previous stage. I see a lot of disadvantages at
> >> pulling out a file, edit away and then pushing it back, while there are
> >> ways to work in a collaborative (and sync) mode.

A wiki is no alternative, because wikimedia (and other wiki software) have 
their own markup (no HTML), and we would have to re-format every wiki page to 
meet the requirements of the Help Browser (even if we would use the HTML 
generated by the wiki software).

> >> 
> >>  We have SVN.. which contains the history of Scribus for (almost)
> >>  ever...
> >> 
> >> I do not believe we have a nice way of extracting from a wiki to our
> >> html format.
> >> 
> >  There is something I don’t get, obviously. :)
> > 
> > See the SVN checkout info on docs.scribus.net or the wiki.
> 
> Do you mean this page?
> http://docs.scribus.net/index.php?lang=en&page=install1

Yes. It might be useful to add an instruction for translators to the 
translation HOWTO about the way to only check out the docs.

> 
> >  Why should we extract something? When we edit a wikipedia page, we edit
> > 
> > the actual page that is shown to the rest of the world.
> > 
> >  The only purpose I would see that would require to extract something is
> > 
> > when we would like to produce a book out of the content of the online
> > doc, using a Scribus template for instance. Then, yes, we would need to
> > extract something.
> > 
> > 
> > We have no intention of producing an online site only.
> 
> Maybe it’s time to revisit some old ideas.
> 
> > Christoph is writing documentation
> 
> We have to ask ourselves why is writing the documentation in the hands of
> only one individual? Wouldn’t it be better if this effort was distributed?
> Only a question and NOT a judgement on the work done.

How did you get the idea that it is in the hands of one individual? As Greg 
has already told you, he has written a lot of new documents himself (probably 
more new documents than I did myself). I just happen to be one of those who 
have commit access to svn. *Everyone* can write a new document and send it to 
one of the developers for review and inclusion.

> 
> > that appears under the Help->Scribus Manual menu entry, as distributed
> > with Scribus.
> 
> Why do we still have to distribute the application with the doc files?
> (maybe the answer is just below, my guess)

Because almost every program that is worth its salt has an Online Help?

> 
> > We have a process that automatically checks out those HTML files and does
> > some data massaging into the format you see on docs.scribus.net... so..
> > from 1 HTML file we get a shipped HTML file with the installed software,
> > plus the online version at docs.scribus.net.
> 
> If I get it well, the point here is to make the doc available when you’re
> offline too, right? But in fact this is probably why it’s so unappealing to
> think of the doc with 49 localized versions. It would be huge, and if we
> add to this the screenshots, it will be even bigger. If the doc is online
> only and not shipped with the application, everything will be easier and
> lighter, don’t you think?

No, especially if you consider that we're working on a feature to access the 
Online Help directly from dialogs, so if you need help with PDF export, you 
can click on a "Help" button, and the Help Browser will open with the relevant 
document on PDF export.

Also, we have to be realists: 49 translations of the docs would be nice, but I 
venture to say that this will never happen. There are more popular Open Source 
projects with only a handful of documentation translations.

> 
> > There is, and never has been, any intention of producing a book from this
> > content.
> 
> I understand that there is and never has been such intention but this is
> exactly what I suggest for the future! Some people need a book — that is
> understandable and acknowledged — but why would the content of this book be
> different (or so different) than what’s available on the website is one
> question I ask. It would simply be repurposing of the same data.

As explained a few emails ago, it would not be the same. We want the Online 
Help to provide short information because reading on screen is more stressful 
to the eyes. The printed manual can provide more details and background 
information. On the other hand, there is information in the Online Help, like 
the Scripter reference or hints for translators, that would just waste space 
(and paper) in a printed book).

> 
> Again, I think that there are some bugs into the doc workflow and I suggest
> ways of making things better.
> 
> I think that the wikipedia way is more appropriate for documentation as SVN
> is probably more suitable for code.

Many Open Source projects (and also closed source software companies) are 
working with a version control system for the documentation. This is a tried 
and tested approach.

Now getting back to an earlier message (sorry, I had some problems with a 
messed-up mailbox after a KDE update):

> > I think we need to put this into perspective. We're talking about the
> > Online Help here. This means that not all screenshots need to be redone
> > for a translation, as only some of them are language/UI-specific.
> 
> Most if not all dialog show at least a few words. If we get a mix of
> languages in the dialog screenshots, it will look like unfinished work and
> to a lot of users it wil not be appealing. From the user perspective I
> don’t think this should even be in discussion.

True this doesn't need to be discussed, but my point is that many screenshots 
do not show any dialogs at all, just content, e.g a selected item on canvas. 
Those need not be redone for every language.

> > Plus, since it's highly unlikely that a translator can work like a
> > machine, the files will be translated one by one, and a translator can
> > create a localised screenshot whenever it's necessary. In other words:
> > there are no robo-translators, thus, no need for robo-screenshots.
> 
> The machine metaphor is certainly funny but it doesn’t help diminish the
> work. Doing screenshots does take time. All I am saying is let’s give a
> hand to translators, show them that we have cared enough to get the work
> started, we have a template, they can concentrate on the translation
> itself, they have the screenshots in their target language and thus the
> right terminology in front of them right at the start of the work. The
> work can also be more easily distributed if all the work is done online.

What you suggest is that we create screenshots automatically (which we can't 
at the moment, and I have no idea how this is supposed to work if we rely on 
specific data in dialogs -- just have a look at the screenshots we currently 
use), for all supported languages. This would mean that we have PNGs with 
screenshots for 40+ languages, most of which will most likely never find 
any/enough translators for the documentation (see above). It's just not worth 
the efforts, and as I wrote in my original email, every translator can create 
the zero up to five screenshots per file himself.

> > And, as Greg already mentioned, we need human beings willing to do the
> > work before we can start the creation of language-specific screenshots.
> 
> The way around. I think we have all the evidences that this doesn’t work.
> The numbers are clear. We have 3 languages out of 49. The doc has been in
> that language state for years as the GUI has evolved a lot faster. I was
> even surprised at the end of the count to be at 49! Wow! If so many people
> care about the GUI translation, I guess that we should understand the
> message.
> 
> > We simply do not know for how many languages there will be volunteers.
> 
> So far, 49 languages.

No. As Craig already wrote, translating the UI is a different beast. UI 
translators only have to translate a few words or phrases, and they can easily 
build upon the work of others. No one needs to start a UI translation of one 
of the 49 languages from scratch, and in some cases, only a small number of 
strings need to be updated. That's quite different from translating continuous 
texts.

> > On the other hand, what would be really useful is a set of sample files
> > that can be used across translations, to make sure that screenshots show
> > the same content in all language versions. This set of files can be
> > created when the update to the English version has been more or less
> > completed.
> 
> Maybe you can explain what you have in mind here. I don’t get the idea.

To give you an example: In the rewritten EPS import doc I added a screenshot 
(English UI) that shows the preview for an EPS file in a file dialog. To make 
the documentation consistent across languages, it would be helpful if the file 
whose preview is shown in the dialog was available somewhere, so that a 
translator could re-create the screenshot with the same content in his 
language. I hope that makes it clear.

Cheers,

Christoph