[Xfce-i18n] Documentation Wiki Online

[Nick Schermer]

On Tue, Jan 10, 2012 at 9:41 PM, Christoph Wickert
<christoph.wickert at googlemail.com> wrote:
> Am Dienstag, den 10.01.2012, 09:17 +0100 schrieb Nick Schermer:
>> On Tue, Jan 10, 2012 at 1:50 AM, Christoph Wickert
>> <christoph.wickert at googlemail.com> wrote:
>>
>> > The wiki raises even more questions:
>> >     1. What about offline documentation? Your initial announcement only
>> >        was about API docs, but user docs should really be installed
>> >        locally I think.
>>
>> I've posted this earlier and also in the blog post:
>
> Yes, you posted it and I am sorry I did not speak up earlier, but AFAIR
> you spoke about API docs and not about handbooks.
>
>> at first we won't
>> have offline docs. Once the manuals start to shape up, we will look
>> into an xfce4-docs package.
>
> I think this is a bad idea. Documentation belongs to the software it's
> about and not into a separate package. Take ristretto for example: We
> now have 0.3.1 without docs, but how do we know if a user is using
> ristretto or another image viewer? If so, why does he need ristretto
> documentation? Or what about people that use ristretto in other desktop
> environment? Should they install the complete docs package while they
> only need one file?

I think 90% of the people has no problems with online docs (and thus
don't need the docs packge). The other 10% probably has no problems
with (20mb?) of decent docs.

>>  I just need content to work with.
>
> As long as there is no documentation about how to work with the wiki, I
> doubt that content will magically appear.

Well it is easy: you ask me nicely, you get an account, login hit the
edit button and start to work.

> Transifex was pretty much self explaining and if not, there was
> documentation. People just sign up and receive instructions from their
> team leader. At docs.xfce.org currently people cannot even register, so
> I really wonder where the content is supposed to come from.

I disabled that for now, but we'll get something nice for that. In the
mean time I will make accounts.

>> >     2. How do we manage users in the wiki? I usually only approve
>> >        people for the German translators team after they have confirmed
>> >        they read various resources and subscribed to the relevant
>> >        mailing list. With the wiki I no longer have control over the
>> >        team.
>> >     3. What should the workflow for submitting and reviewing
>> >        translations look like? We have strings that undergo 3 or 4
>> >        reviews until all people are happy. How would you do this in the
>> >        wiki where every random person can edit any file?
>>
>> Maybe you don't, but I have. We can create separate teams per-language.
>
> How exactly would we do that? Can we have people that manage individual
> teams? Can a manager approve or reject team members? How does a user
> request membership in a team? Does the team lead get notifications when
> people want to join?

We can point to the transifex translation team, I the coordinator
approved somebody (most likely an existing team member) I setup the
account.

>> >     4. We have translators who want to work offline with their favorite
>> >        tools such as poedit or vim. How can they do this in the wiki?
>>
>> You can write wiki content offline too. If you copy the English
>> source, you can easily translate it.
>
> But it includes wiki syntax and writing this offline without visible
> control is hard. Not to mention that people need to learn yet another
> wiki syntax and dokuwiki is not necesarrily the most popular one.

The wiki syntax is much easier then the docbook/mallard xml syntax in
the gettext strings. And yes, quite often distcheck was broken because
of missing xml tags.

>> >     5. How do we handle translator credits?
>>
>> We can put that in the footer of a page, imho your free to do what you
>> want in your translated pages.
>
> Don't we want this to be consistent across the languages? How do we
> enforce consistency?
>
>> > I appreciate your intention to have better docs, but to me it looks like
>> > this idea was not thought trough and needed more discussion.
>>
>> Too late.
>
> I don't think that I was too late but that you were too early. :)

I waited 2 years for proper docs, nothing happened, and now I'm quick? Sigh...

> The whole idea doesn't look well thought through and as long as there is
> no consensus, one should not change a thing.
>
>> This path leads to better english docs and I value that more then
>> translated docs that are not there or don't apply.
>
> Maybe it leads to more docs, but I doubt it leads to better docs if
> everybody can just work on it.

Not everybody, I never said anything like that. Separate groups will
work on the English docs and the translator groups will work on the
wiki pages.

The wiki lowers the barrier to to contribute, that is more important
then translations.

>> The wiki runs the
>> translation plugin, just like wiki.xfce.org, so once pages start to
>> shape up (english), each team can work on the translations.
>
> Ok, is there some documentation about this? How does the translation
> plugin work? Do we need to use certain URLs or namespaces?
>
>> The way I see it, is that for example the German team has say 4 wiki
>> contributors.
>
> We have way more people and coordination will become hard in the wiki.

But do they all need wiki access. Wikipedia works quite well, and I
suspect more people work on those pages.

>> Someone translates a page, you folks discuss it on a ml
>> or whatever and then it is committed in the wiki.
>
> Are you suggesting we submit a wiki page with wiki syntax to the mailing
> list for discussion? It's bounced back and forth and quoted again and
> again. I doubt there is anything useful left after a few iterations.

Just thinking here. If I was the German team I'd distribute the work
and when someone finishes, put the content online (it won't be that
bad) and then ask for review, other translators can edit/discuss
whatever.

>> You can also put a
>> note in the top of the page the translation is being worked on and
>> people comment internally on sections.
>
> Marking a whole page as draft is not the same as marking individual
> strings in a po file as fuzzy.

The plugin tells if the english version is never when the translated
version. Translators need to look at the diff log when. Less easy then
fuzzy strings for sure, but not impossible.

> And what is "internally" in this context? Where should communication
> take place?

xfce-i18n-de.

> I know traisfex was not perfect, but it had everything we needed:
> Whenever I see something fuzzy, I review it. Clean and simple. What
> would the workflow for a wiki page look like?

Nick