[libreoffice-l10n] Proposal: Documentation workflow and cooperation between NL teams

classic Classic list List threaded Threaded
8 messages Options
Wheatbix Wheatbix
Reply | Threaded
Open this post in threaded view
|

[libreoffice-l10n] Proposal: Documentation workflow and cooperation between NL teams

Hi David et al,
As I had promised, it is Boxing day, and my idea has been developed
into something more than just a scribble on a scrap of paper.

http://wiki.documentfoundation.org/File:LibreOffice_documentation_workflow_proposal.odp

The idea is to promote structured coordination between documentation
language teams to allow concepts and content to flow from one language
to another without restricting how the concept is implemented in any
NL document.
I have built the idea from the documentation workflow that Jean
proposed we use from the OOoAuthors site, including an editing and
review process for every proposed change regardless of language.

I am not sure what direction language teams have taken regarding
documentation and if this proposal fits in with any existing plans,
could someone comment on this?

I would appreciate feedback to the open questions at the end of the
document, if you have a constructive opinion, I am more than happy to
adapt the approach if something is more appropriate / better outcome.

Thanks all for the positive input and support so far with the
Documentation Team.
Michael Wheatland

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://listarchives.libreoffice.org/www/l10n/
*** All posts to this list are publicly archived for eternity ***
eskroni eskroni
Reply | Threaded
Open this post in threaded view
|

[libreoffice-l10n] Re: [libreoffice-documentation] Proposal: Documentation workflow and cooperation between NL teams

Hi Michael,

thanks for your proposal. I had a quick look at it.

2010/12/26 Michael Wheatland <[hidden email]>:

> Hi David et al,
> As I had promised, it is Boxing day, and my idea has been developed
> into something more than just a scribble on a scrap of paper.
>
> http://wiki.documentfoundation.org/File:LibreOffice_documentation_workflow_proposal.odp
>
> The idea is to promote structured coordination between documentation
> language teams to allow concepts and content to flow from one language
> to another without restricting how the concept is implemented in any
> NL document.
> I have built the idea from the documentation workflow that Jean
> proposed we use from the OOoAuthors site, including an editing and
> review process for every proposed change regardless of language.
>
> I am not sure what direction language teams have taken regarding
> documentation and if this proposal fits in with any existing plans,
> could someone comment on this?
>
> I would appreciate feedback to the open questions at the end of the
> document, if you have a constructive opinion, I am more than happy to
> adapt the approach if something is more appropriate / better outcome.

To answer some of your open questions:

We should also have a look at pootle, since Sophie is running a test
to use it for translation purposes (see her announcement here:
<http://go.mail-archive.com/Hn9qvZS2yGYyXSWq7P0JtElbvo0=> ). Pootle is
a tool, that is known to many translators, so it might be useful to
take it into account as well. We'll see what the result is of this
test.

Btw, I'm not sure, that Jean recommended using the Wiki for developing
the documentation. I would say it was more the opposite. :)

I would like to have a common template among all the languages, so I'm
in favour of this idea.

For having the same structure: I think, the headings are chosen to
have a logical layout and flow of the text. So in my opinion, it would
make sense to have a similar structure in the other languages as well.
But I would not force other language teams to have the same structure.
Maybe there is a good reason, why they want to change it.

So I'll stop here for now - if I have more to say, I'll send another mail. ;)

Sigrid

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://listarchives.libreoffice.org/www/l10n/
*** All posts to this list are publicly archived for eternity ***
Charles-H. Schulz Charles-H. Schulz
Reply | Threaded
Open this post in threaded view
|

Re: [libreoffice-l10n] Proposal: Documentation workflow and cooperation between NL teams

In reply to this post by Wheatbix
Hello Mike,


Le Mon, 27 Dec 2010 02:37:34 +0930,
Michael Wheatland <[hidden email]> a écrit :

> Hi David et al,
> As I had promised, it is Boxing day, and my idea has been developed
> into something more than just a scribble on a scrap of paper.
>
> http://wiki.documentfoundation.org/File:LibreOffice_documentation_workflow_proposal.odp
>
> The idea is to promote structured coordination between documentation
> language teams to allow concepts and content to flow from one language
> to another without restricting how the concept is implemented in any
> NL document.
> I have built the idea from the documentation workflow that Jean
> proposed we use from the OOoAuthors site, including an editing and
> review process for every proposed change regardless of language.
>
> I am not sure what direction language teams have taken regarding
> documentation and if this proposal fits in with any existing plans,
> could someone comment on this?
>
> I would appreciate feedback to the open questions at the end of the
> document, if you have a constructive opinion, I am more than happy to
> adapt the approach if something is more appropriate / better outcome.
>
> Thanks all for the positive input and support so far with the
> Documentation Team.
> Michael Wheatland


Thank you for your input. I think that we have never been able to come
up with one unified workflow in the past, and I would advise against
getting too formal here. We would probably discourage a lot of people.
So let's keep things simple, shall we? :-)

Anyone can draft a documentation , in its own language, and may the
best one win!

Best,
Charles.
>


--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://listarchives.libreoffice.org/www/l10n/
*** All posts to this list are publicly archived for eternity ***

eskroni eskroni
Reply | Threaded
Open this post in threaded view
|

Re: [libreoffice-l10n] Proposal: Documentation workflow and cooperation between NL teams

Hi Charles,


2010/12/26 Charles-H. Schulz <[hidden email]>:
> Hello Mike,
>
>
> Le Mon, 27 Dec 2010 02:37:34 +0930,
> Michael Wheatland <[hidden email]> a écrit :
>

[...]

>
> Thank you for your input. I think that we have never been able to come
> up with one unified workflow in the past, and I would advise against
> getting too formal here. We would probably discourage a lot of people.
> So let's keep things simple, shall we? :-)
>
> Anyone can draft a documentation , in its own language, and may the
> best one win!

That's true. But the lack of having a unified workflow in the past
should not stop us from trying to get one now. It might discourage
people that's right, but it also might have the opposite effect, if
you can see, that there's a way that your documentation might be used
around the world. I find this idea very encouraging.

So let's wait and see what others might have to say.

Sigrid

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://listarchives.libreoffice.org/www/l10n/
*** All posts to this list are publicly archived for eternity ***
marcpare4 marcpare4
Reply | Threaded
Open this post in threaded view
|

[libreoffice-l10n] Re: Proposal: Documentation workflow and cooperation between NL teams

In reply to this post by Charles-H. Schulz
Le 2010-12-26 15:47, Charles-H. Schulz a écrit :

> Thank you for your input. I think that we have never been able to come
> up with one unified workflow in the past, and I would advise against
> getting too formal here. We would probably discourage a lot of people.
> So let's keep things simple, shall we? :-)
>
> Anyone can draft a documentation , in its own language, and may the
> best one win!
>
> Best,
> Charles.
>>
>
>

We should not look at this as a competition. These are options. All
stakeholders should take a close look at different options and try to
pick what is best to work with even if it means adapting one or the
other and including what is best out of both. A third option built out
of these two may make more sense.

Making this into a competition is counter-productive to the membership
and creates camps for no reason at all. Consensus is the reasonable way
to operate as well as membership building.

Marc


--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://listarchives.libreoffice.org/www/l10n/
*** All posts to this list are publicly archived for eternity ***

davidnelson davidnelson
Reply | Threaded
Open this post in threaded view
|

[libreoffice-l10n] Re: [libreoffice-documentation] Proposal: Documentation workflow and cooperation between NL teams

In reply to this post by Wheatbix
Hi Michael, :-)

Thanks for this input and creative thinking. Objective examination of
contrasting ideas is a great way to identify the best way forward.

I've read your presentation and sat there thinking about your ideas,
but I don't think we hit the jackpot yet. Let me explain why.

1) Your system sees documentation and other i18n-able content being
processed within a unified work process. You yourself alluded to the
complexity of such a system. I see that as a problem because a) it
will take quite some time and considerable development work to
implement, and b) it will impose a degree of technical expertise and a
learning curve on i18n and English docs people that might be beyond
many.

2) Your system deprives i18n teams/individuals of the current
flexibility and freedom of action that is one of the founding
principles behind TDF. They would be obliged to work as "minions"
(said with a *big* *humorous* smile) of a "big machine" that does not
let them address and implement any NL-specific needs and approaches.

We have to bear in mind that i18n is done by teams ranging in size
from one solitary individual to a number of contributors, and they
have varying degrees of technical expertise, as well as varying
degrees of willingness to learn new systems that would get imposed on
them. IMHO, by offering people total freedom of action, but backed up
by a good level of support if they want to adopt existing workflows,
tools and content, we are likely to draw-in a lot more contributors ot
the community of communities.

To better explain what I mean, I refer you to my recent post
explaining TDF's i18n policy, such as I have come to understand it
(see [1]).

My humble suggestion would be to keep thinking, but focus on a
workflow for the English documentation team. If we really come up with
something that is a real winner, it is likely to be naturally adopted
by at least *some* i18n teams. But, IMHO, a "standardized", "global",
"factory" approach is unlikely to win widespread support.

While you're thinking, I'd invite you to evaluate the current options
up for discussion:

1) Andreas Mantke's and Jean Weber's work on their Plone-based web;

2) The Alfresco evaluation sandbox I've got installed at
https://documentation.traduction.biz which might work for the "English
docs" team and for any i18n teams interested in collaborating closely
with "English docs", whether on a "translation-based" approach or on
an "own content creation" approach (or a mixture of the two);

3) A wiki-based approach;

3) Any other system you see as advantageous (which I am betting would
be Drupal-based :-D ).

HTH. ;-)

[1] http://nabble.documentfoundation.org/How-do-I-contribute-to-Documentation-and-l10n-tp2141125p2147769.html

David Nelson

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://listarchives.libreoffice.org/www/l10n/
*** All posts to this list are publicly archived for eternity ***

andréb andréb
Reply | Threaded
Open this post in threaded view
|

Re: [libreoffice-l10n] Proposal: Documentation workflow and cooperation between NL teams

In reply to this post by Wheatbix
Michael Wheatland a écrit :

> Hi David et al,
> As I had promised, it is Boxing day, and my idea has been developed
> into something more than just a scribble on a scrap of paper.
>
> http://wiki.documentfoundation.org/File:LibreOffice_documentation_workflow_proposal.odp
>
> The idea is to promote structured coordination between documentation
> language teams to allow concepts and content to flow from one language
> to another without restricting how the concept is implemented in any
> NL document.
> I have built the idea from the documentation workflow that Jean
> proposed we use from the OOoAuthors site, including an editing and
> review process for every proposed change regardless of language.
>
> I am not sure what direction language teams have taken regarding
> documentation and if this proposal fits in with any existing plans,
> could someone comment on this?
>
> I would appreciate feedback to the open questions at the end of the
> document, if you have a constructive opinion, I am more than happy to
> adapt the approach if something is more appropriate / better outcome.
>
> Thanks all for the positive input and support so far with the
> Documentation Team.
> Michael Wheatland

The concept of "content changes" vs. "language changes" is very useful.
  (I would favour saying "language-specific" to avoid confusion.)

One problem with using a numbering system for content changes, is that
many changes will be redundant and/or contradictory, or not useful in
certain contexts.
So if we do versioning of content changes, there should be a means for
each language group to tag a particular change :
- New
- Applied/committed
- In process/assigned
- Ignored if not considered useful
- Pending if undecided

As well, it would be useful to have the date of creation, and creating
language group.

Since version numbers would supposedly be created when the content
change is committed, the "mini-release" would not be known at that time.

Language groups not wanting to translate by content change need only
translate by documentation modules of some other language.
Thus I don't think that the content change approach should be forced on
any language group.
Commit controls could still be used for groups translating by
documentation modules.

Although I do agree that for language groups with enough translators,
documentation would be more up to date and more uniform with the content
change approach.

As for implementation, language groups that choose to translate by
module could possibly be well served by a wiki or mailing list.
Which would not work well with the content change approach.

The reality is that for many languages with few translators, there will
be only those "less skilled" in technical writing.  Those translators
would problably do much better translating by documentation module,
where they would more easily see everything in context.  So we should
focus on helping such groups, and not try to block them.

As far as existing documentation goes, we should try to ensure it is
structured around the modules / menu system / functions of LibreOffice.
(This seems to be the case for French documentation.)
As long as the documentation is structured in this way, it seems better
to give free reign to translation groups.
In other words, don't try to enforce sentence-by-sentence translation.
We risk to find better ways to explain/document LibreOffice.

If we create a reference structure based on LibreOffice functionality,
and migrate this structure into existing documentation, we should end up
with a system that lets us easily compare the documentation of any 2
languages.
Any documentation that doesn't fit into the reference structure could
lead to modifying the structure, if found to be an oversight.

(Don't know how we should treat such documentation in comparisons, etc.)

I think we should start with existing documentation and evolve.

As far as synchonising content between languages, that should happen
naturally once the reference structure is integrated into the language
version, and comparison tools are available.

As mentioned above, I favour using a documentation structure based on
LibreOffice modules and menus/functions, which will naturally lead to
common sections, and headings should correspond.
However I would leave it to the language groups to decide how to present
each section.  It would be far easier to do a more or less direct
translation, but if the group felt that there was a better way to
document, they should be free to do so.
This can lead to migrating better documentation to other languages.

A professional look can be achieved by a non-obligatory style guide.

A suggested standard look could be useful, but I wouldn't make it a
requirement.  There could be good historical/cultural reasons to vary
for a particular language.

my 2 cents :)
André

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://listarchives.libreoffice.org/www/l10n/
*** All posts to this list are publicly archived for eternity ***
Wheatbix Wheatbix
Reply | Threaded
Open this post in threaded view
|

Re: [libreoffice-l10n] Proposal: Documentation workflow and cooperation between NL teams

2010/12/28 andré b <[hidden email]>:

> Michael Wheatland a écrit :
>>
>> Hi David et al,
>> As I had promised, it is Boxing day, and my idea has been developed
>> into something more than just a scribble on a scrap of paper.
>>
>>
>> http://wiki.documentfoundation.org/File:LibreOffice_documentation_workflow_proposal.odp
>>
>> The idea is to promote structured coordination between documentation
>> language teams to allow concepts and content to flow from one language
>> to another without restricting how the concept is implemented in any
>> NL document.
>> I have built the idea from the documentation workflow that Jean
>> proposed we use from the OOoAuthors site, including an editing and
>> review process for every proposed change regardless of language.
>>
>> I am not sure what direction language teams have taken regarding
>> documentation and if this proposal fits in with any existing plans,
>> could someone comment on this?
>>
>> I would appreciate feedback to the open questions at the end of the
>> document, if you have a constructive opinion, I am more than happy to
>> adapt the approach if something is more appropriate / better outcome.
>>
>> Thanks all for the positive input and support so far with the
>> Documentation Team.
>> Michael Wheatland
>
> The concept of "content changes" vs. "language changes" is very useful.  (I
> would favour saying "language-specific" to avoid confusion.)
>
> One problem with using a numbering system for content changes, is that many
> changes will be redundant and/or contradictory, or not useful in certain
> contexts.
> So if we do versioning of content changes, there should be a means for each
> language group to tag a particular change :
> - New
> - Applied/committed
> - In process/assigned
> - Ignored if not considered useful
> - Pending if undecided
>
> As well, it would be useful to have the date of creation, and creating
> language group.
>
> Since version numbers would supposedly be created when the content change is
> committed, the "mini-release" would not be known at that time.
>
> Language groups not wanting to translate by content change need only
> translate by documentation modules of some other language.
> Thus I don't think that the content change approach should be forced on any
> language group.
> Commit controls could still be used for groups translating by documentation
> modules.
>
> Although I do agree that for language groups with enough translators,
> documentation would be more up to date and more uniform with the content
> change approach.
>
> As for implementation, language groups that choose to translate by module
> could possibly be well served by a wiki or mailing list.
> Which would not work well with the content change approach.
>
> The reality is that for many languages with few translators, there will be
> only those "less skilled" in technical writing.  Those translators would
> problably do much better translating by documentation module, where they
> would more easily see everything in context.  So we should focus on helping
> such groups, and not try to block them.
>
> As far as existing documentation goes, we should try to ensure it is
> structured around the modules / menu system / functions of LibreOffice.
> (This seems to be the case for French documentation.)
> As long as the documentation is structured in this way, it seems better to
> give free reign to translation groups.
> In other words, don't try to enforce sentence-by-sentence translation.
> We risk to find better ways to explain/document LibreOffice.
>
> If we create a reference structure based on LibreOffice functionality, and
> migrate this structure into existing documentation, we should end up with a
> system that lets us easily compare the documentation of any 2 languages.
> Any documentation that doesn't fit into the reference structure could lead
> to modifying the structure, if found to be an oversight.
>
> (Don't know how we should treat such documentation in comparisons, etc.)
>
> I think we should start with existing documentation and evolve.
>
> As far as synchonising content between languages, that should happen
> naturally once the reference structure is integrated into the language
> version, and comparison tools are available.
>
> As mentioned above, I favour using a documentation structure based on
> LibreOffice modules and menus/functions, which will naturally lead to common
> sections, and headings should correspond.
> However I would leave it to the language groups to decide how to present
> each section.  It would be far easier to do a more or less direct
> translation, but if the group felt that there was a better way to document,
> they should be free to do so.
> This can lead to migrating better documentation to other languages.
>
> A professional look can be achieved by a non-obligatory style guide.
>
> A suggested standard look could be useful, but I wouldn't make it a
> requirement.  There could be good historical/cultural reasons to vary for a
> particular language.
>
> my 2 cents :)
> André

Thanks for the great feedback André,

I think you may be on the right track with this suggestion, and let me
summarise your points to make sure I understand them:

 + Version numbering is not required
 + Each 'Content change' should be reviewed by NL editors and the
action/non-action taken and the item tagged as such
 + We need to discuss structure more and agree on a 'reference
structure' which will be used to compare documents across NL, mapping
parts of the reference structure to parts of the NL documentation.
 + A non-compulsary international style guide should be developed
 + A non-compulsary international documentation template should be developed
 + Non-compulsary international re-usable elements (Pages / Tables /
Frames / Embeds) should be developed
 + Once these are developed then each documentation team can integrate
what they want into the existing documentation
 + Each NL documentation team will collaborate using infrastructure
they choose, separate to the change management system
 + For smaller NL documentation teams there would be no need to follow
these changes, but rather translate individual documents from another
established NL document.

Let me know if I misunderstood or missed any of your points.
I really appreciate this very in depth and constructive feedback. I
have cross-posted this to the en-documentation mailing list for
discussion there. As this is a system which is designed for all
languages NL input is critical.

Again Thanks,
Michael Wheatland

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://listarchives.libreoffice.org/www/l10n/
*** All posts to this list are publicly archived for eternity ***