Re: [perldoc2-developers] [RFC] Platform Specification Vs. 0.1

[Robert 'p. S. <rs...@47...>]

Hi Joergen and everyone else listening;

Joergen W. Lang said:
> The first version of the specification for the platform is ready for
> your perusal.
>
> Please comment, add, edit, ask ... after all these are just a few
> thoughts out of my own twisted brain.

Thanks for the effort and the (convenient, for us) explicit specification=
.
Here are my first thoughts. It might get a bit hard to keep all the ideas
and decisions in memory. So I thought, maybe we should set up a wiki or
something along that for this process?

Anyway, here's my braindump:

---

As I have a rather lenghty answer of comments, I'll skip the line
numbers and refer to the sections instead. I will also keep it rather
short, as squirremail dropped my previous mail. I hereby officially
curse PHP once more.

** Section "Goals":

> The final goal is to provide complete translations of
>
> - the core documentation(1)
> - the documentation of the core modules(2)

As I understand it, we actually want to be "P6-proof," and able to
easily make this facility available to other projects or even
programming languages. I first thought this might be premature
optimization. But this more affects the categorization and meta
data of the projects themselves, rather than the actual translation
process. So I think it might be worth trying to make the application
aware of metadata in an abstract sense, and not "Perl version numbers"
themselves for example.

** Section "Multilingual"

> Since this is a translation platform, the contents and interfaces of th=
e
> website should be available in as many natural languages as possible.

We might even start a translation project for it! (just a joke)

Seriously though, I18N shouldn't be a problem, independent of the used
web framework.

** Section "Framework"

> We should not reinvent the wheel. There already is a good choice of web
> application frameworks out there. Choosing one written in Perl might
> help us - and Perl at the same time. ;o)

Full Ack. I'd still be happy to hear from other members what their
favorite web development platforms are and why.

** Section "Adoption"

> The 'adoption' method could be an essential part of the project. By
> assigning a complete document to one physical person, this person is
> encouraged to make the translation a personal effort instead of feeling
> like an anonymous gear within the big translation machine.

I'd also like to propose the role of a "language adopter," who can overse=
e
an entire language. The document adopters are document and language speci=
fic,
as I understand them.

** Section "COMPONENTS - repository"

> For the moment we use an SVN repository on sourceforge to collect and
> store the documents to be translated and the already existing
> translations. This might change during the developement of the project
> as it might be more practical to store the documents within the databas=
e.

++ for the database on my side. It makes enhancements, keeping track and
metadata much easier than trying to set that up above another layer.

** Section "COMPONENTS - interface(s)"

> The platform might have several different interfaces. One for
> translators, one for end users and for administrators.

I'd think two (web) interfaces might be enough. One for project members a=
nd
one for project users. As the administrator privileges could be integrate=
d
in the general translation interface.

> - submit errata
> - give general feedback

I'd propose the terms "comment" and "errata" for submissions. These could
also be accepted from non-registered users (but with Captcha for spam
prevention, of course). Furthermore, I think it might be a good idea to
design these in form of a small trouble-ticket system. Where these states
would be possible:

comments:
- unread
- acknowledged (with response)

errata:
- new
- rejected (with reason)
- acknowledged (or open)
- closed (with comment)

A public viewable list of comments/errata per document and per language
would also help to prevent to duplicate issues.

** Section "COMPONENTS - people"

> Sometimes decisions have to be made wether a certain word should be
> translated one way or the other or not a all. This might need one or
> more 'referees' of some kind.

I'd much rather prefer language-specific mailing-lists. This would also
provide a public viewable archive of reasonings behind certain things,
and a place for "outsiders" to address larger issues, which wouldn't fit
into "comments" or "errata" submissions.

** Section "Additional Features"

> - RSS feeds for
> -- statistics
> -- news
> -- ?

-- documents with newly translated parts
-- documents with newly approved parts
-- documents with newly abandoned parts
-- comments/errata

The first three could be shown in a changeset style of view.

> - IRC-Channel?

Of course! It has more than one advantage: It eases development of the
platform, it provides a direct source for help and to drop comments, it
is a nice meeting point and it generally keeps the involved parties
close together.

- Mailing lists

As stated above, I'd recommend per language lists additional to the
regular ones.

** Section "Workflow"

I would like to address a general issue here: There won't be core
project attendees for every language. This means that specific issues
in other languages can only be handled if there are "trusted" members
of the translation move. I therefore would propose a slightly more
complex hierarchy of roles and privileges:

- Administrators (should be clear)

- Language Adopters (Can "administrate" one language. These are the
  primary contacts for language global issues. Can influence all
  documents of one language)
- Document Adopters (Should be per language. Can influence one document
  in a specific language)

- Core Translators (Can check-out, check-in, etc. These are the "trusted"
  translators in the project. Can approve translations.)
- Wingman/Reviewer (A Core Translator assigned to another one for the
  purpose of QA.)
- Translators (Cannot approve. Can only checkout a limited number of
  document "parts". Can be promoted to Core Translators if found
  trustworthy enough. Maybe it should take one core translator to
  check-in changes, and a second one to approve to ensure quality.)

The Administrators would be the only language-independent roles. An
adopter role can only be carried by a core translator.

We might also want to allow the end-users to create accounts. So they
can keep public/private notes, store bookmarks etc.)

** Section "DETAILS - Database"

> What else?

I would suggest to wait with details about the database schema until we
agreed on what has to go inside and what structure we need.

** Section "DETAILS - Status of document"

> A document, stored in an SVN repository, a database or whereever, has a
> certain status attached to it.

I'd rather attach states to the parts of a document, rather than the whol=
e
document itself. By this we can dynamically accumulate states of document=
s
and languages.

Though we'd need different states or state indicators for documents and
document parts then. How about something along these:

Document states:
- vacant
- adopted

Document part states:
- not translated
- in translation
- translated but not approved
- translated and approved (read: finished)

I'd say it should be possible for a translator to check out specific part=
s
of a document (say, parts 15 to 23). These would then be in the "in
translation" state. The limit of parts to check out should be influenced
by the role (core translator or just translator) of the user. As you
stated, after a specified time, depending on the number of checked out
parts, this state should be revoked. The claimed parts would be "not
translated" again. The revocation counter should be reset on any activity
in the checked out parts, so we would need to regard a checkout as an
entity by itself.

Of course, if a translator has problems with a specific part, it should b=
e
possible for him to "drop" the part back to "not translated" but keep the
others checked out.

** Section "DETAILS - Meta information"

> - (Perl) version the document is based upon.

Wouldn't it be more open-ended if we'd make the projects hierarchical?
So there wouldn't be an explicit need for perl version number metadata.

E.g.

- Perl 5
  - Version 5.6
    - Core Documentation
    - Core Module Documentation
  - Version 5.8
    - Core Documentation
    - Core Module Documentation
- Perl 6
  ...

** Section "DETAILS - User registration"

> For reasons of security and consistency it is probably neccessary for
> users to register with the project as a translator/reviewer/... (aha -
> we already have different roles!)

Of course!

** Section "DETAILS - Checkout"

> A registered user will be able to assign one (or more?) documents to
> himself. This person will be the "adopter" for this document for a
> certain amount of time (the "time to live", "TTL", see "Abandoned
> documents").

I wouldn't let the adopters expire, but rather make the adoption of
something an administrative/overseeing role. I'd actually propose a
primary and a secondary adopter per document and language. The secondary
one could be chosen by the primary adopter himself, in case he's not
available. For reasons of vacation, or too much work, for example.

** Section "DETAILS - Review"

> A concept of peer review similar to that of wikipedia could be used.
> Other users are encouraged to review and to correct. Maybe this could
> follow the "buddy principle" as practiced with divers.

I agree with the "buddy" idea, except that I find the term "wingman" way
cooler. This might be a personal preference though ;)

> To review a document the 'buddy' needs to checkout the document and
> actually read it.  By re-submitting it the document will be marked as
> 'finished'.

If we introduce per-document-part states, the reviewing process might
even go along with the translation of certain parts of the document.
When the translator stores a part of his checkout as "finished," his
wingman would get it on his todo list for review. He can then either
approve the translation, or reject it (with a reason). The latter drops
it onto the translators todo list for his checkout again.

** Section "DETAILS - Check-in"

> The check-in or 'submit' of translated documents could be acchieved in
> one of the following ways:
>
> - Upload via HTML-Form
> - email (to a special address handling the integration of the document
>   into the database).

Well, I'd see some possibilities to check-out/check-in the document parts=
.
A first separation would be "online" or "offline." So I'd propose to keep
the checkout state canonically online, and allow status updates by checki=
ng
in offline edited documents.

Online translation would probably be a web interface. A saving of a
document part there would also be a request for review.

Offline editing would need some specified formats for export, which shoul=
d
be able to carry metadata. These would come to mind:

* XML

The metadata would be no problem. They could be edited directly, or with
an editor. Maybe Herbert can write us something fancy for this in Wx ;) A
client application could also check-out the todo-list of claimed items
via a webservice.

* POD

Of course I don't mean the original POD, but something specified. For
example:

  =3Dhead1 Translation Todo List

  $some_generic_information

  =3Dhead2 ORIGINAL[$metadata]

  $original_text

  =3Dhead2 TRANSLATION[$metadata]

  =3Dbegin TRANSLATION PLACEHOLDER (please erase when translation finishe=
d)

  $original_text

  =3Dend

  =3Dhead2 ORIGINAL[$metadata]

  ...

* po4a

I don't really know po4a's metadata capabilities, so I can't comment on
this.

The metadata in the formats allows for an easy synchronization. The check=
ed
out document would contain the parts the translator has on it's translati=
on
todo-list. He can start translating them and occasionally check the
document back in. Through placeholders like "TRANSLATION PLACEHOLDER"
above, the system can just extract the finished parts and send it to the
wingman for review. It can also insert those parts the wingman has alread=
y
rejected, with his reasonings in "=3Dbegin REJECTION REASON" blocks.

This would allow for offline editing and occasional synchronisation with
the online application to stay up to date.

---

So, please let me know what you think of these points.

gr.,
Robert

--=20
# Robert 'phaylon' Sedlacek
# Perl 5/Catalyst Developer in Hamburg, Germany
{ EMail =3D> ' rs...@47... ', Web =3D> ' http://474.at ' }