[Xfce-i18n] Documentation Wiki Online

[Christoph Wickert]

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

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.

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

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

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

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.

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

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

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

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

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?

Regards,
Christoph