2010/11/30 Christoph Schäfer <span dir="ltr">&lt;<a href="mailto:christoph-schaefer@gmx.de">christoph-schaefer@gmx.de</a>&gt;</span><br><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
On Mittwoch, 1. Dezember 2010 01:06:57 Louis Desjardins wrote:<br>
&lt;snip&gt;<br>
<br>
My impression is that the discussion is getting a bit out of hand, probably<br>
due to misunderstandings and people talking past each other.<br>
<div class="im"><br>
&gt; &gt;&gt;  Can we turn this into a wikipedia-like way to go? If for some reason<br>
&gt; &gt;&gt;<br>
&gt; &gt;&gt; someone makes an error and mixes things or deletes some content, we have<br>
&gt; &gt;&gt; ways to return to the previous stage. I see a lot of disadvantages at<br>
&gt; &gt;&gt; pulling out a file, edit away and then pushing it back, while there are<br>
&gt; &gt;&gt; ways to work in a collaborative (and sync) mode.<br>
<br>
</div>A wiki is no alternative, because wikimedia (and other wiki software) have<br>
their own markup (no HTML), and we would have to re-format every wiki page to<br>
meet the requirements of the Help Browser (even if we would use the HTML<br>
generated by the wiki software).<br></blockquote><div><br></div><div>Thanks for the explanation. I understand much better. So the bottleneck is this, the Help Browser. </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">

<div class="im"><br>
&gt; &gt;&gt;<br>
&gt; &gt;&gt;  We have SVN.. which contains the history of Scribus for (almost)<br>
&gt; &gt;&gt;  ever...<br>
&gt; &gt;&gt;<br>
&gt; &gt;&gt; I do not believe we have a nice way of extracting from a wiki to our<br>
&gt; &gt;&gt; html format.<br>
&gt; &gt;&gt;<br>
&gt; &gt;  There is something I don’t get, obviously. :)<br>
&gt; &gt;<br>
&gt; &gt; See the SVN checkout info on <a href="http://docs.scribus.net" target="_blank">docs.scribus.net</a> or the wiki.<br>
&gt;<br>
&gt; Do you mean this page?<br>
&gt; <a href="http://docs.scribus.net/index.php?lang=en&amp;page=install1" target="_blank">http://docs.scribus.net/index.php?lang=en&amp;page=install1</a><br>
<br>
</div>Yes. It might be useful to add an instruction for translators to the<br>
translation HOWTO about the way to only check out the docs.<br></blockquote><div><br></div><div>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.</div>
<div><br></div><div>Translators welcome ! :)</div><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im"><br>
&gt;<br>
&gt; &gt;  Why should we extract something? When we edit a wikipedia page, we edit<br>
&gt; &gt;<br>
&gt; &gt; the actual page that is shown to the rest of the world.<br>
&gt; &gt;<br>
&gt; &gt;  The only purpose I would see that would require to extract something is<br>
&gt; &gt;<br>
&gt; &gt; when we would like to produce a book out of the content of the online<br>
&gt; &gt; doc, using a Scribus template for instance. Then, yes, we would need to<br>
&gt; &gt; extract something.<br>
&gt; &gt;<br>
&gt; &gt;<br>
&gt; &gt; We have no intention of producing an online site only.<br>
&gt;<br>
&gt; Maybe it’s time to revisit some old ideas.<br></div></blockquote><div><br></div><div>Again, maybe it’s time to revisit some old ideas.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">
&gt;<br>
&gt; &gt; Christoph is writing documentation<br>
&gt;<br>
&gt; We have to ask ourselves why is writing the documentation in the hands of<br>
&gt; only one individual? Wouldn’t it be better if this effort was distributed?<br>
&gt; Only a question and NOT a judgement on the work done.<br>
<br>
</div>How did you get the idea that it is in the hands of one individual? As Greg<br>
has already told you, he has written a lot of new documents himself (probably<br>
more new documents than I did myself). I just happen to be one of those who<br>
have commit access to svn. *Everyone* can write a new document and send it to<br>
one of the developers for review and inclusion.<br></blockquote><div><br></div><div>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.</div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im"><br>
&gt;<br>
&gt; &gt; that appears under the Help-&gt;Scribus Manual menu entry, as distributed<br>
&gt; &gt; with Scribus.<br>
&gt;<br>
&gt; Why do we still have to distribute the application with the doc files?<br>
&gt; (maybe the answer is just below, my guess)<br>
<br>
</div>Because almost every program that is worth its salt has an Online Help?<br></blockquote><div><br></div><div>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.)?  </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im"><br>
&gt;<br>
&gt; &gt; We have a process that automatically checks out those HTML files and does<br>
&gt; &gt; some data massaging into the format you see on docs.scribus.net... so..<br>
&gt; &gt; from 1 HTML file we get a shipped HTML file with the installed software,<br>
&gt; &gt; plus the online version at <a href="http://docs.scribus.net" target="_blank">docs.scribus.net</a>.<br>
&gt;<br>
&gt; If I get it well, the point here is to make the doc available when you’re<br>
&gt; offline too, right? But in fact this is probably why it’s so unappealing to<br>
&gt; think of the doc with 49 localized versions. It would be huge, and if we<br>
&gt; add to this the screenshots, it will be even bigger. If the doc is online<br>
&gt; only and not shipped with the application, everything will be easier and<br>
&gt; lighter, don’t you think?<br>
<br>
</div>No, especially if you consider that we&#39;re working on a feature to access the<br>
Online Help directly from dialogs, so if you need help with PDF export, you<br>
can click on a &quot;Help&quot; button, and the Help Browser will open with the relevant<br>
document on PDF export.<br></blockquote><div><br></div><div>A kind of super tooltips system... interesting. </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
Also, we have to be realists: 49 translations of the docs would be nice, but I<br>
venture to say that this will never happen. There are more popular Open Source<br>
projects with only a handful of documentation translations.<br></blockquote><div><br></div><div>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.</div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im"><br>
&gt;<br>
&gt; &gt; There is, and never has been, any intention of producing a book from this<br>
&gt; &gt; content.<br>
&gt;<br>
&gt; I understand that there is and never has been such intention but this is<br>
&gt; exactly what I suggest for the future! Some people need a book — that is<br>
&gt; understandable and acknowledged — but why would the content of this book be<br>
&gt; different (or so different) than what’s available on the website is one<br>
&gt; question I ask. It would simply be repurposing of the same data.<br>
<br>
</div>As explained a few emails ago, it would not be the same. We want the Online<br>
Help to provide short information because reading on screen is more stressful<br>
to the eyes. The printed manual can provide more details and background<br>
information. On the other hand, there is information in the Online Help, like<br>
the Scripter reference or hints for translators, that would just waste space<br>
(and paper) in a printed book).<br></blockquote><div><br></div><div>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.</div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im"><br>
&gt;<br>
&gt; Again, I think that there are some bugs into the doc workflow and I suggest<br>
&gt; ways of making things better.<br>
&gt;<br>
&gt; I think that the wikipedia way is more appropriate for documentation as SVN<br>
&gt; is probably more suitable for code.<br>
<br>
</div>Many Open Source projects (and also closed source software companies) are<br>
working with a version control system for the documentation. This is a tried<br>
and tested approach.<br></blockquote><div><br></div><div>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. </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
Now getting back to an earlier message (sorry, I had some problems with a<br>
messed-up mailbox after a KDE update):<br>
<div class="im"><br>
&gt; &gt; I think we need to put this into perspective. We&#39;re talking about the<br>
&gt; &gt; Online Help here. This means that not all screenshots need to be redone<br>
&gt; &gt; for a translation, as only some of them are language/UI-specific.<br>
&gt;<br>
</div><div class="im">&gt; Most if not all dialog show at least a few words. If we get a mix of<br>
&gt; languages in the dialog screenshots, it will look like unfinished work and<br>
&gt; to a lot of users it wil not be appealing. From the user perspective I<br>
&gt; don’t think this should even be in discussion.<br>
<br>
</div>True this doesn&#39;t need to be discussed, but my point is that many screenshots<br>
do not show any dialogs at all, just content, e.g a selected item on canvas.<br>
Those need not be redone for every language. </blockquote><div><br></div><div>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.</div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"> </blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im"><br>
&gt; &gt; Plus, since it&#39;s highly unlikely that a translator can work like a<br>
&gt; &gt; machine, the files will be translated one by one, and a translator can<br>
&gt; &gt; create a localised screenshot whenever it&#39;s necessary. In other words:<br>
&gt; &gt; there are no robo-translators, thus, no need for robo-screenshots.<br>
&gt;<br>
</div><div class="im">&gt; The machine metaphor is certainly funny but it doesn’t help diminish the<br>
&gt; work. Doing screenshots does take time. All I am saying is let’s give a<br>
&gt; hand to translators, show them that we have cared enough to get the work<br>
&gt; started, we have a template, they can concentrate on the translation<br>
&gt; itself, they have the screenshots in their target language and thus the<br>
&gt; right terminology in front of them right at the start of the work. The<br>
&gt; work can also be more easily distributed if all the work is done online.<br>
<br>
</div>What you suggest is that we create screenshots automatically (which we can&#39;t<br>
at the moment, and I have no idea how this is supposed to work if we rely on<br>
specific data in dialogs -- just have a look at the screenshots we currently<br>
use), for all supported languages. This would mean that we have PNGs with<br>
screenshots for 40+ languages, most of which will most likely never find<br>
any/enough translators for the documentation (see above). It&#39;s just not worth<br>
the efforts, and as I wrote in my original email, every translator can create<br>
the zero up to five screenshots per file himself.<br></blockquote><div><br></div><div>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. </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im"><br>
&gt; &gt; And, as Greg already mentioned, we need human beings willing to do the<br>
</div><div class="im">&gt; &gt; work before we can start the creation of language-specific screenshots.<br>
&gt;<br>
&gt; The way around. I think we have all the evidences that this doesn’t work.<br>
&gt; The numbers are clear. We have 3 languages out of 49. The doc has been in<br>
&gt; that language state for years as the GUI has evolved a lot faster. I was<br>
&gt; even surprised at the end of the count to be at 49! Wow! If so many people<br>
&gt; care about the GUI translation, I guess that we should understand the<br>
&gt; message.<br>
&gt;<br>
</div><div class="im">&gt; &gt; We simply do not know for how many languages there will be volunteers.<br>
&gt;<br>
</div>&gt; So far, 49 languages.<br>
<br>
No. As Craig already wrote, translating the UI is a different beast. UI<br>
translators only have to translate a few words or phrases, and they can easily<br>
build upon the work of others. No one needs to start a UI translation of one<br>
of the 49 languages from scratch, and in some cases, only a small number of<br>
strings need to be updated. That&#39;s quite different from translating continuous<br>
texts.<br></blockquote><div><br></div><div>Of course if we look at this by saying &quot;no&quot;, 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.</div>
<div><br></div><div>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.</div>
<div><br></div><div>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?</div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im"><br>
&gt; &gt; On the other hand, what would be really useful is a set of sample files<br>
&gt; &gt; that can be used across translations, to make sure that screenshots show<br>
&gt; &gt; the same content in all language versions. This set of files can be<br>
&gt; &gt; created when the update to the English version has been more or less<br>
&gt; &gt; completed.<br>
&gt;<br>
</div><div class="im">&gt; Maybe you can explain what you have in mind here. I don’t get the idea.<br>
<br>
</div>To give you an example: In the rewritten EPS import doc I added a screenshot<br>
(English UI) that shows the preview for an EPS file in a file dialog. To make<br>
the documentation consistent across languages, it would be helpful if the file<br>
whose preview is shown in the dialog was available somewhere, so that a<br>
translator could re-create the screenshot with the same content in his<br>
language. I hope that makes it clear.<br></blockquote><div><br></div><div>Pretty much clear, yes. Thanks.</div><div><br></div><div>Cheers,</div><div><br></div><div>Louis</div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">

<br>
Cheers,<br>
<font color="#888888"><br>
Christoph</font></blockquote></div>