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

[Louis Desjardins]

2010/11/30 Christoph Schäfer <christoph-schaefer at gmx.de>

> 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).
>

Thanks for the explanation. I understand much better. So the bottleneck is
this, the Help Browser.

>
> > >>
> > >>  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.
>

You guessed right. This was implicit into my question. This page has useful
info. However written in a way that makes it somewhat difficult to
non-initiated to follow. If only the acronyms were explained. All these SVN,
VNC and then all the veresionning of Scribus are a closed language that is
already a barrier to a lot of people. And the info is not complete. And the
way it is put is not appealing as well.

Translators welcome ! :)

In Paris we have discussed about ways of getting more people in the project.
One of those ways was to revisit the website, the info that is there and how
do we welcome new-comers. This has to be thought over in its globality. For
example, on the website’s front page there is no explicit link to welcome
people who want to give a hand — coding, debugging, translating, writing
tutorials, etc. — but the info *is* available somewhere. We need to fix this
my making that info available at first glance.


>
> >
> > >  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.
>

Again, 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.
>

I guess that we have to make that far more obvious in many ways, including
what needs to be documented, what is the status for the current
documentation, in details — because for instance when I read that once docs
for version 1.x is out, then we’re focusing on 1.y and 1.x will be outdated,
I have to wonder about what exactly will be outdated. In my view, even if
the program is under big big big work, much of what is written about each
feature remain true nonetheless. We are still in typography, still in DTP,
still in prepress, still in PDF output, stil in texts and font issues and
color management. So basically unless we rephrase and rephrase all the time
the same basic informations, lots of this stuff is VERY unlikely going to
change. BUT in fact what we need here is a real STATUS for each and every
part of the documentation. Only then will we know precisely what is still
good, what needs that we add a bit of nuances due to added functionnality,
or new functionnality, etc. General statements in this area is NOT helpful
and only contributes to the global blur around something that should be much
more straightforward, in fact.

>
> >
> > > 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?
>

Well, I mean why not only URL to the doc website? And from there, all the
extra help? (wiki, IRC, mailing list, other links, etc.)?

>
> >
> > > 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.
>

A kind of super tooltips system... interesting.

>
> 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.
>

Maybe *49* is never going to happen. Or maybe it could happen. But we have
to face it: the way this whole workflow is set now must have *some* effect
on the fact that those docs are not more translated than they are. The wrong
conclusion here would be to state that there is no need for this or that
there are no translators interested... Maybe people just don’t know where to
go, what to start with, etc. Maybe we’re not exactly welcoming. This is a
question, not a statement.

>
> >
> > > 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).
>

To me all this is only a matter of how we display the information. When
working on a document, what people need is to sort out rapidly a very
specific issue. Most of those issues can already be solved by appropriate
tooltips — a very nice way to help. A bit more reading for more complex
issues. The doc is actually a sum of many small bits of informations.

>
> >
> > 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.
>

But you have mentionned also that many great apps out there don’t have so
many translated docs. Again, maybe, maybe this whole workflow is super
interesting from the administrators point of view but fail to provide a
working playground that is appealing enough to a vast majority of
translators — or doc writers.

>
> 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.


Sure. But this doesn’t prove the point I raise to be wrong. And by the way,
I think that we should refrain from using words like *many* and put numbers
there instead. Only to help figure out the work that would need to be done.

>


> > > 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.
>

It’s really only a matter of diskspace at this point, and download time.
There are certainly ways to manage this at installation time. Download the
application, then download your language. Just like OO.o does it. Easy,
understandable, quick. Actually, there are 3 steps: the applications, the
most recent patch, the language.

>
> > > 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.
>

Of course if we look at this by saying "no", we will never get anywhere.
Translating the UI is not that simple as you have to look for the right
terminogy (a time-consuming task, sometimes) that can (that should) be
re-used when translating the docs. In fact, everyone here will work on the
work of others.

And I have to insist on the fact that this is not really continuous text as
well... It’s an addition of small articles. When we look at the
documentation closely enough, we can see the small parts and we can work on
each of them.

Very down-to-earth questions. How do I know what work remains to be done
before the doc for 1.4 is complete? Where do I look for? Is there a list of
features, articles, notes, tooltips, etc., that I can look for, browse and
seach and even review what has already been written and or updated so far?
Is there a progression bar or a graph that will help me understand what has
been done and what remains to be done. Do we have a schedule, an evaluation
of the time it takes to write 20 lines of fresh documentation and how many
lines are expected to be written — just as a target and based on previous
work — on such and such features? In other words, what is the plan for
documentation?

>
> > > 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.
>

Pretty much clear, yes. Thanks.

Cheers,

Louis

>
> Cheers,
>
> Christoph
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.scribus.net/pipermail/scribus-dev/attachments/20101201/609dd8de/attachment-0001.htm>