Date: prev next · Thread: first prev next last
2010 Archives by date, by thread · List index


2010/12/28 andré b <andr55@laposte.net>:
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 l10n+help@libreoffice.org
List archive: http://listarchives.libreoffice.org/www/l10n/
*** All posts to this list are publicly archived for eternity ***

Context


Privacy Policy | Impressum (Legal Info) | Copyright information: Unless otherwise specified, all text and images on this website are licensed under the Creative Commons Attribution-Share Alike 3.0 License. This does not include the source code of LibreOffice, which is licensed under the Mozilla Public License (MPLv2). "LibreOffice" and "The Document Foundation" are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy.