2010/12/28 andré b <[email protected]>: > 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 [email protected] List archive: http://listarchives.libreoffice.org/www/documentation/ *** All posts to this list are publicly archived for eternity ***
