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

[Christoph Schäfer]

On Mittwoch, 1. Dezember 2010 09:01:16 Louis Desjardins wrote:

(I'll remove everything unnecessary from the previous emails, as this thread 
has become one of those who might let "War and Peace" look like a short story)


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

No! The Help Browser is only a "bottleneck" if you insist on using something 
like a wiki that uses a different markup. The Help Browser uses standard HTML, 
but we have a set of rules for the doc files, also a subset of HTML, since the 
OH docs are also used for the content available via docs.scribus.net. Craig 
already explained it.


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

One thing that I have experienced in different projects is that a basic level 
of skills is required for participation, and using a versioning system is 
certainly one of them. The same is true for journalists who have to work with 
their editing software and many other jobs. Using svn is really simple, but I 
will look into improving the doc.
 
> 
> 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.

Yes, we know. Alex is working on a relaunch of the website, but as far as I 
can tell, he's currently mighty busy with his dayjob.


> 
> Again, maybe it’s time to revisit some old ideas.

These are not old ideas.


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

Let me phrase it as follows: We don't need subordinates, but people who take 
the initiative. The first step to determine whether something needs to be 
documented is to actually read the existing docs. It's easy to find the holes 
that still exist in the documentation. The next step would be to contact the 
team to get advice on how to write an additional document. A potential 
contributor should also be aware of the documentation license, and he or she 
should have some writing skills, because rewriting a bad text is as much, if 
not more work than writing it from scratch. It also goes without saying that 
someone who wants to contribute to the documentation needs some experience 
with Scribus. 

I will add a document that contains some hints for those interested in 
contributing.

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

Well, I don't want to sound snarky, but you just wrote down some general 
statements ;) If you look at the bug report you quoted further up in the 
thread, it describes the status of certain parts of the documentation. While 
it's true that we're still dealing with typography, pre-press etc., you should 
actualĺy read what is there. The outdated documentation is several years old 
and has been written when 1) Scribus was only available for Linux and b) the 
technical infrastructure on Linux was in a shape that required many ugly 
workarounds. Much of those are no longer necessary, and that's why the 
documentation needs an update ... urgently (for more details I refer to the 
bug report).


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

First, why don't you fire up Scribus 1.3.7, 1.3.8 or 1.3.9 and look under 
"Help"? There are menu entries with links to to online resources. As for 
"only", the answer is a definitive "no". You will find the reasons in previous 
messages by different people in this thread and you even mentioned one 
yourself (offline work).


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

Obviously the process of participation is not as transparent as it should be, 
agreed. But as mentioned above, Alex is working on a redesign of the website, 
which will make this more obvious and welcoming.


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

We obviously disagree on the different uses of an online documentation and a 
book ;) Let's assume you are correct. How do you explain, then, the existence 
of hundreds of thousands of printed books about software in general and even 
development tools or programming languages for which extensive online 
documentation exists (e.g. Python, Java, LaTeX)? Moreover, relying solely on 
online documents for a program whose main purpose is to create printed 
documents while there are countless books on creating web content seems quite 
strange to me ...


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

I wrote many. Many doesn't mean all. As for the rest, see above (re: basic 
skills)


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

It's a bit hard to come up with numbers when the documentation is a moving 
target and changes as we speak. But you can do the math yourself with 1.3.9 
(once the DMG is up on Sourceforge), since all the images are part of the 
package.


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

Mentioning OO.o here is very valuable input, because I think that's what we 
should be heading for, *once* the number of complete translations requires it. 
For now, we use a fallback mechanism, i.e., if there's no translated version 
is available, the English file will be used instead, and since all 
translations have been disabled for now, only English is being shown.


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

Even a small (or not so small article) is by definition continuous text, as 
opposed to "File ...", "Save As ..." etc.

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

Unfortunately there is no such plan, and at this point in time I doubt whether 
it makes sense to set one up. There is, however, an "invisible" plan, which is 
determined by existing holes in the existing documentation (see above). But 
even if we had a plan or a roadmap, every potential author would still have to 
read the existing documentation to find out what has already been described, 
so that unnecessary work can be avoided by cross-referencing. This also 
reminds me of another difference between a printed manual and the Online Help: 
Some topics in the Online Help have been dealt with in single paragraphs of a 
larger document. That's not a problem, since the Help Browser has search and 
bookmark features. In a printed manual, these issues can be treated separately 
and more detailed in their own chapters or sections.

Cheers,

Christoph