1. 1 Documentation Workflow Proposal By Michael Wheatland LibreOffice Documentation Team 2010-12-27

2. Requirements All languages across the LibreOffice community should be equal

3. 3 Documentation Team Challenges The needs of the international community

4. Reasoning behind establishing an international documentation workflow Official Documentation should be of high quality across all languages Direct Translation of English Documents are not always appropriate. Language forks of documentation is not collaborative, 'working together' as a community would likely result in better documentation.

5. Existing Documentation Workflow Does not support submitting changes back to the English documentation in a structured way http://wiki.services.openoffice.org/wiki/User:Nnino/Drafts/Oooauthors_Workflow

6. 6 Idea for documentation development

7. Use of existing resources There are already existing documentation in a few languages. The official documentation templates, initially developed within the documentation list. Help files, Wiki Help and the soon to be wiki.libreoffice.org can provide suggestions for documentation changes 'Reusable elements' as suggested by Jean should be used across documents and languages and developed to be acceptable by all languages (LTR and RTL adaptation or compatible elements with both should be developed)

8. The idea In order for all language teams to work together in a constructive way an orderly structure needs to be developed. A customised workflow can be created to propose and moderate changes in language groups. Changes which would be useful across any language can be flagged as a 'content change' Changes which are reworking the document in a specific language, but not adding more information would not be flagged as content changes. From here on I will be referring to these as 'content changes' and 'language changes'.

9. How do we keep track of 'content changes'? In order for all language teams to work together in a constructive way an orderly structure needs to be developed. If we consider these 'content changes' to be a 'patch' in much the same way that programming code is submitted to GIT for inclusion into LibreOffice we can use a numbering system Each 'content change' would have a unique number assigned to it. If a 'content change' patch has not been applied to your language's documentation this would reflect in the numbering.

10. Catch-up for under-resourced language teams Not all language teams will have the resources to keep up to date with rapid documentation development We need to provide a way for (some) languages to translate / rework a whole document rather than implementing many 'patches' We could create 'mini-releases' of documentation common to all languages. Under-resourced language teams may wish to translate only the mini-releases while larger language teams would keep up to date with the patch process.

11. Tracking of changes A numbering system, similar to software release could be used: 3.3-111.222en333 A numbering system to track the changes could be: 3.3 = Applies to LibreOffice release 111 = mini-release of documentation 222 = Content Changes en = Indication of documentation language 333 = Language specific

12. Tracking of changes It looks complicated! 3.3-111.222en333 We can present this in a better way using a workflow tool. There is no need for contributors to see the actual number, but it can be used by editors / moderators to check that changes are sequential and do not overwrite older changes. The numbering we choose could be included into the ODT document somewhere so document coordinators can double check submissions.

13. 13 How could we implement this? The tools to use for this development

14. Analysis of existing tools Alfresco Was discussed on the Mailing list. Great for single language development, but would not support multilingual development. Version Control Systems (GIT) A lot of command line work and documentation teams would need to learn a new system, changes to implement across languages would have to be tracked on a different system. Wiki Very intuitive, but free form, changes are not always enforceable by the central documentation team. - Recommendation by Jean Drupal Customizable workflow system which would allow simple click to propose changes to documents, editing and moderation by approved people, easy tracking of relevant changes and not reliant on user input for any of the workflow resulting in accurate tracking.

15. Drupal Website Development Team Drupal has been earmarked as the primary content management system by the Steering Committee. We have people who are able and willing to 'create' the workflow that the documentation team wants, and it can be adapted later if changes are required. The system can enforce that proposed changes are checked by a documentation editor and approved prior to publishing or propagating the change across languages. - As recommended by Jean.

16. 16 Open Questions and Feedback

17. Open Question: Infrastructure I admit to being biased towards Drupal Can another system support this multilingual infrastructure without custom coding? Is there a better option for implementation?

18. Open Question: Workflow The proposed workflow would require editors and Co-ordinators from each language Can smaller languages be sufficiently supported by multilingual editors/coordinators? Should we allow people 'less skilled' in technical writing become documentation co- ordinators/approvers due to lack of people? Jean might have an opinion on this

19. Open Question: Cooperation or Forking Some languages already have individual documentation Do we want to cooperate between languages to improve content? Do we want to fork documentation content or is most of the 'content' common to all languages?

20. Open Question: Merging If we decide to go about cooperating across languages as this workflow has suggested How do we go about merging/synchronising 'content' between languages? Should we synchronise documentation structure (Headings and sections)?

21. Open Question: Formatting / Layout We want the documents to look professional across all languages. Should we ask the design team to revise our template to suit internationalisation? Should we adopt a standard template and reusable elements across all languages? Would a standard look be appropriate?

22. Feedback Please I do not pretend to know every viewpoint in the community, if you disagree with any of these concepts please raise your concern and suggest an alternative Although I speak English and this proposal/discussion is in English there should be no bias towards using the English documentation as a starting point, the highest quality documents should be used. Constructive feedback is very welcome.

23. All text and image content in this document, unless otherwise specified, is licensed under the Creative Commons Attribution-Share Alike 3.0 License. This does not include the LibreOffice name, logo, or icon.Creative Commons Attribution-Share Alike 3.0 License 23 Thank you! Please send feedback... LibreOffice documentation mailing list LibreOffice Drupal website wiki page http://wiki.documentfoundation.org/Website/Drupal/Documentation