PHP Documentation - Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes

Author

Re: [PHP-DOC] EN-Revision comments Vs Docbook revision attributes

Hannes Magnusson

2007-10-06, 8:00 am

On 8/30/07, Philip Olson <philip@roshambo.org> wrote:
>
> On Aug 18, 2007, at 8:42 AM, Fernando Correa da Conceição wrote:
>
>
> If there's a better way then let's do it... please propose exactly
> how it'd work and what it would look like. We'd also need to adjust
> all the translation scripts within docweb (and scripts/) before/while
> implementing.

(See attached patched for function.strpos on how exactly it will look
in the XML)

The rules would be the same as CVS Revision, just manually bumped.

When not to bump:
- WS fixes
- (non-important) typos changes
- (non-important) grammar changes
- Totally irrelevant changes for translations
....

When to bump minor version (after the dot):
- Minor content fixes
- Important typos (referring to wrong function for instance)
- Example fixes
....

When to bump major version (before the dot):
- Security fixes (in examples or text recommendations..)
- When adding new section to a page
- Otherwise major changes

Just use your commonsense when bumping major/minor version.
The difference in bumping major vs minor revisions is how the user
will see the difference.

For instance, if a translation is couple of minor revisions old the
end-user will see tiny little yellow warning stating "this translation
is little old, no _important_ changes have been done though".
If the translation is a whole major revision old the end-user will see
a big fat red warning: "This page is out of date! Please consider to
view the English version!"

-Hannes

Nuno Lopes

2007-10-06, 7:01 pm

> > > Hannes Magnusson escreveu:
>
> (See attached patched for function.strpos on how exactly it will look
> in the XML)
>
> The rules would be the same as CVS Revision, just manually bumped.

I don't like this idea because the revision doesn't get bumped
automatically. I think there'll be more problems that the little efforth of
the translators to bump a no-op revision.
Please remember that not everybody that contributes documentation belongs to
the phpdoc team and thus isn't aware of our latest practices. So, automatic
things are the best things (tm).

Nuno

Kouber Saparev

2007-10-08, 8:04 am

Hannes Magnusson Ð½Ð°Ð¿Ð¸ÑÐ°:
> On 8/30/07, Philip Olson <philip@roshambo.org> wrote:
>
> (See attached patched for function.strpos on how exactly it will look
> in the XML)
>
> The rules would be the same as CVS Revision, just manually bumped.
>
> When not to bump:
> - WS fixes
> - (non-important) typos changes
> - (non-important) grammar changes
> - Totally irrelevant changes for translations
> ...
>
> When to bump minor version (after the dot):
> - Minor content fixes
> - Important typos (referring to wrong function for instance)
> - Example fixes
> ...
>
> When to bump major version (before the dot):
> - Security fixes (in examples or text recommendations..)
> - When adding new section to a page
> - Otherwise major changes
>
> Just use your commonsense when bumping major/minor version.
> The difference in bumping major vs minor revisions is how the user
> will see the difference.
>
> For instance, if a translation is couple of minor revisions old the
> end-user will see tiny little yellow warning stating "this translation
> is little old, no _important_ changes have been done though".
> If the translation is a whole major revision old the end-user will see
> a big fat red warning: "This page is out of date! Please consider to
> view the English version!"
>
> -Hannes
>

Although it should not bother the current work of English writers, the
idea of telling the end-user that something is out of date and that,
either a minor or a major change was introduced, is great. It is
important to have correct translations and since it's not that easy to
maintain all the changes, it's substantial to at least inform the end-user.

I guess it would increase the build time, since a diff might be needed
for each file and not just a simple check whether a file is present or not.

--
Kouber Saparev
http://kouber.saparev.com

Kouber Saparev

2007-10-08, 8:04 am

Return-Path: <kouber@php.net>
Mailing-List: contact phpdoc-help@lists.php.net; run by ezmlm
Delivered-To: mailing list phpdoc@lists.php.net
Received: (qmail 10936 invoked by uid 1010); 8 Oct 2007 11:07:43 -0000
Delivered-To: ezmlm-scan-phpdoc@lists.php.net
Delivered-To: ezmlm-phpdoc@lists.php.net
Received: (qmail 10920 invoked from network); 8 Oct 2007 11:07:43 -0000
Received: from unknown (HELO lists.php.net) (127.0.0.1)
by localhost with SMTP; 8 Oct 2007 11:07:43 -0000
X-Host-Fingerprint: 213.16.46.130 pirus.securax.be
Received: from [213.16.46.130] ([213.16.46.130:23463] helo=localhost.localdomain)
by pb1.pair.com (ecelerity 2.1.1.9-wez r(12769M)) with ESMTP
id 72/D2-17330-E7F0A074 for <phpdoc@lists.php.net>; Mon, 08 Oct 2007 07:07:42 -0400
To: phpdoc@lists.php.net
Reply-To: kouber@saparev.com
User-Agent: Thunderbird 2.0.0.6 (Windows/20070728)
MIME-Version: 1.0
In-Reply-To: <001901c80824$f6fe87a0$4001a8c0@pc07653>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
X-Posted-By: 213.16.46.130
Xref: mail.webservertalk.com php.doc:4612

Nuno Lopes Ð½Ð°Ð¿Ð¸ÑÐ°:
> I don't like this idea because the revision doesn't get bumped
> automatically. I think there'll be more problems that the little efforth
> of the translators to bump a no-op revision.
> Please remember that not everybody that contributes documentation
> belongs to the phpdoc team and thus isn't aware of our latest practices.
> So, automatic things are the best things (tm).
>
> Nuno

Well, in case there's a special "by default" level, it will not break
the automatic bump of the revision. That level could be the "minor" one
proposed by Hannes, for example. On the contrary, when a critical
(major) change is introduced, it's important to tell the translators to
pay much more attention on it. I believe major changes are important
enough to spend some 2-3 seconds on tagging/commenting them accordingly.
It's a matter of communication and respect between us.

--
Kouber Saparev
http://kouber.saparev.com

Philip Olson

2007-10-11, 10:02 pm

Personally I'm unable to throw my vote towards any particular method
at this time but feel we're getting somewhere and that this topic
won't be forgotten. Ideally even more people will weigh in with
ideas, especially translators, for how best to approach this. There
are several good ideas floating around so to summarize them
(including my thoughts):

---
(A) The proposal with manually updated revision numbers. One for
minor, another for major. (Hannes)

I don't see forgetfulness (which would no doubt happen from time to
time) as a solid enough reason to scrap this idea entirely because we
have a strong enough peer review to combat that. Overall it's a nice
proposal but see below.

(B) Automatic revision increments by default, with ability to
manually disable the increment per commit. (Leonardo)

This is my current favourite (but how best to implement?) as it's
essentially the best of both worlds.

(C) Use the CVS commit message to designate status, and use scripts/
tools to parse. (Jakub)

A similar idea here is we could (in addition to B above) do this to
mark 'critical' commits in the message, and then a tool would let
translators know which files still require these critical fixes. In
fact, we may even consider 'hiding' these pages (via the build) by
showing EN/ versions until they are in fact translated.

(D) Have it all automatic, as done currently. (Nuno)

Hopefully the above thoughts help ease these concerns.

(E) ? (?)
---

And even though it's a good start, what we decide here won't be the
magical bullet that'll solve our translation problems. I can't speak
from experience but strongly urge all translators to think about this
entire topic and brainstorm for methods to help better manage the
translations. Is it simply a lack of volunteer time? Or is the
difficulty of working with the manual sources the main problem? Do we
need better tools? Is file ownership ever an issue? How does Japanese
bionic man Masahiro do it all? And while we're at it, let's ensure
the following is correct and wise:

http://doc.php.net/php/dochowto/chapter-translation.php

And regardless of what we do here, the idea of declaring outdated
translated text as outdated (and linking to en/) via the build system
will be done. Livedocs did it, and PhD will too. Right Hannes? ;-)

Regards,
Philip

Simion Onea

2007-10-12, 4:01 am

> -----Original Message-----
> From: Philip Olson [mailto:philip@roshambo.org]
> Sent: Friday, October 12, 2007 3:30 AM
> To: kouber@saparev.com
> Cc: PHPdoc List; Hannes Magnusson
> Subject: Re: [PHP-DOC] EN-Revision comments Vs Docbook
> revision attributes
>
>
> Personally I'm unable to throw my vote towards any particular
> method at this time but feel we're getting somewhere and that
> this topic won't be forgotten. Ideally even more people will
> weigh in with ideas, especially translators, for how best to
> approach this. There are several good ideas floating around
> so to summarize them (including my thoughts):
>
> ---
> (A) The proposal with manually updated revision numbers. One
> for minor, another for major. (Hannes)
>
> I don't see forgetfulness (which would no doubt happen from time to
> time) as a solid enough reason to scrap this idea entirely
> because we have a strong enough peer review to combat that.
> Overall it's a nice proposal but see below.
>
> (B) Automatic revision increments by default, with ability to
> manually disable the increment per commit. (Leonardo)
>
> This is my current favourite (but how best to implement?) as
> it's essentially the best of both worlds.
>
> (C) Use the CVS commit message to designate status, and use
> scripts/ tools to parse. (Jakub)
>
> A similar idea here is we could (in addition to B above) do
> this to mark 'critical' commits in the message, and then a
> tool would let translators know which files still require
> these critical fixes. In fact, we may even consider 'hiding'
> these pages (via the build) by showing EN/ versions until
> they are in fact translated.
>
> (D) Have it all automatic, as done currently. (Nuno)
>
> Hopefully the above thoughts help ease these concerns.
>
> (E) ? (?)
> ---
>
> And even though it's a good start, what we decide here won't
> be the magical bullet that'll solve our translation problems.
> I can't speak from experience but strongly urge all
> translators to think about this entire topic and brainstorm
> for methods to help better manage the translations. Is it
> simply a lack of volunteer time? Or is the difficulty of
> working with the manual sources the main problem? Do we need
> better tools? Is file ownership ever an issue? How does
> Japanese bionic man Masahiro do it all? And while we're at
> it, let's ensure the following is correct and wise:
>
> http://doc.php.net/php/dochowto/chapter-translation.php
>
> And regardless of what we do here, the idea of declaring
> outdated translated text as outdated (and linking to en/) via
> the build system will be done. Livedocs did it, and PhD will
> too. Right Hannes? ;-)
>
> Regards,
> Philip

Hi !

Since I do not know deeply all the intricacies of CVS and PhD, I cannot opt
for one of the proposals above. (C) looks too 'artificial' in my opinion.
When I first joined the team as a translator it was rather difficult and it
took me some time to figure out how everything works. It would be nice to
make the Howto more detailed and more 'newbie oriented' if someone has the
time, of course.
Also in the beginning it was difficult for me to figure out the status of
the entire translation. The page at http://doc.php.net/php/ro/revcheck.php
showed outdated information although we made commits to the 'ro' tree. Only
when I figured out how to run 'revcheck' locally I got the real picture. Is
it difficult to put this script somewhere on cvs.php.net so that it always
checks the latest data?
These are my thoughts for now.

Best regards,
Simion.

Sponsored Links