OpenStack documentation & translation management 2012_summit

© 2009 IBM Corporation

OpenStack Documentation and Translation Management

The OpenStack SummitSan Diago 2012

Ying Chun Guo (Daisy)OpenStack Doc Teamguoyingc@cn.ibm.com

Anne GentleOpenStack Doc Teamanne@openstack.org

2www.openstack.org

Agenda

Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Plans for next steps

Questions with Answers

3www.openstack.org

Agenda

Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Plans for next steps

Questions with Answers

www.openstack.org

文档页面Web Page for Documentation

http://docs.openstack.org

5www.openstack.org

Challenges of Community Document

Large amount of code

Change frequently

Grow quickly

Loose coupling

Manage document as code !

6www.openstack.org

Document Process: Design

Blueprints and discussion at Design Summit

Blueprints

Current blueprints found at https://blueprints.launchpad.net/openstack-manuals

7www.openstack.org

Document Process：Development

Github repositories store admin guides and API guides

Unit tests with Jenkins

Patch review with Gerrit

8www.openstack.org

Document Process：Bug tracking

Manage bugs through LanuchpadBug loggingBug triagingBug assigning

9www.openstack.org

Document Process： Publishing

Automatically publish with Jenkins

10www.openstack.org

Doc Team Composition

All OpenStack community members

One percenters = OpenStack-doc-core

Badge WearersAT&T IBMNebulaNiciraNimbis ServicesNuageRackspaceRedHat

11www.openstack.org

Statics

20+ Compute Extensions documented at api.openstack.org

66% Site visitors stay instead of leaving

100 Doc patches and reviews a month

726 Configuration options : 467 for nova.conf, 259 for swift conf files

10,000 Unique visitors a week at docs.openstack.org

12www.openstack.org

Agenda

Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Plans for next steps

Questions with Answers

13www.openstack.org

Challenges of Document Translation

Large amount of code

Change frequently

Grow quickly

Loose coupling

Manage document translation as code string translation!

14www.openstack.org

Translation Process： Slicing

Slice DocBook into string segment with a Python script, and generate a PO template

./tools/generatepot openstack-compute-admin

15www.openstack.org

Translation Process： Translating

Manage translation by TransifexTranslation project & resourcesTranslation memoryGlossary

16www.openstack.org

Translation Process：Merging

Merge the translated string into Docbook with a python script.

./tools/generatedocbook -l zh_CN -b openstack-compute-admin

17www.openstack.org

Translation Process：Uploading & Downloading

Upload the translation resources and download the translated results by commands of Transifex Client.

tx set --auto-local -r openstack-manuals-i18n.openstack-api-programming 'doc/src/docbkx/openstack-api-programming/locale/<lang>.po' --source-lang en --source-file doc/src/docbkx/openstack-api-programming/locale/openstack-api-programming.pot –execute

tx pull -f -l zh_CN -r openstack-manuals-i18n.api-quick-start

tx push -s -r openstack-manuals-i18n.api-quick-start

18www.openstack.org

Translation Process： Change Management

Synchronize the local translation resources with the resources in the Transifex server by Transifex Client commands.

Command “tx push” will automatically check the differences and merge the local copy and remote copy.

New strings will be added.Modified strings will be considered new ones and added as well.Strings which do not exist in the new source file (including ones which have been modified) will be removed from the database.The removed translations are kept in the Translation Memory of your project.

./tools/generatedocbook -l zh_CN -b openstack-manuals-i18n.api-quick-start

tx push -s -r openstack-manuals-i18n.api-quick-start

tx pull -r openstack-manuals-i18n.api-quick-start

19www.openstack.org

Statics

5 languages translation startedChinese – 11%, Spanish – 5%, Czech – 3%, Korean, French

15+ translators contributed.

Chinese translations“OpenStack API Quick Start” 100% finished“Network Administration Guide” 59% finished“OpenStack Install and Deploy Manual” 44% finished

20www.openstack.org

Agenda

Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Plans for next steps

Questions with Answers

www.openstack.org 21

Sample： Chinese Document Generation

Step 1: Check out the sources from Git repositorygit clone https://github.com/daisy-ycguo/openstack-manuals-i18n.git

Step 2: Check out the latest translation from Transifextx pull -f -l zh_CN -r openstack-manuals-i18n.api-quick-start

www.openstack.org

Sample： Chinese Document Generation

Step 3: Merge the translation segments back to DocBook./tools/generatedocbook -l zh_CN -b api-quick-start

Step 4: Generate PDF and HTML documentmvn generate-sources

23www.openstack.org

Agenda

Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Plans for next steps

Questions with Answers

www.openstack.org

Plans for next steps

Integrate the process into Continuous Integration system.Slicing & uploadingDownloadingMerging & publishing to website automaticallyUpdating

Resolve the issue: lack of translation context after slicing into statements.

Using a website to show the up-to-date translated documents, to facilitate the translators to check their translation results at any time.

Any kinds of contributions to translation process is warmly welcomed !

25www.openstack.org

Agenda

Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Questions with Answers

Plans for next steps

26www.openstack.org

How can I get on the openstack-core-docs team?

Do lots of reviews at http://review.openstack.org for the openstack-manuals project.

Triage bugs and log doc bugs at http://bugs.launchpad.net/openstack-manuals.

We’ll discuss on the openstack-docs-core mailing list and then invite you.

27www.openstack.org

How should I find doc work that needs to be done on a particular project?

Refer to http://bugs.launchpad.net/openstack-manuals and look for Wishlist for tasks, or any doc bug can be picked up as a work item.

We also track few blueprints which may need someone to work on, though doc bugs are probably the best first place to look

28www.openstack.org

Who should do reviews of my document changes?

Anne Gentle, the doc coordinator, or anyone on the openstack-doc-core team can help you identify reviewers, or you can also check the doc bug and ask the reporter to review the changes by adding their name to the reviewers list.

29www.openstack.org

How to contribute the translations？

If you want to contribute the translations, you need to register an account at Transifex, and then go to openstack-manuals translation page.

After that, select the languages you prefer, all of the language resources will be listed. Then select the resources you want to work on and click it. Click “Translate Now” in the pop-up dialog.

30www.openstack.org

How to get the latest translation documents？

Check out the latest resources from Git repository at first, and then check out the latest translation from Transifex. After that, merge the translation segment back to DocBook by running the Python script and generate PDF and HTML document by running Maven build.

Refer to “Sample: Chinese Document Generation”

31www.openstack.org

Conclusion

Managing document as code is key feature of OpenStack documentation.

The translation is just started. I will need the support and participation from all of you.

Your participation is warmly welcomed.

For any problems about documentation, please contact with Anne Gentle.

For any problems about translation, please contact with Ying Chun Guo.

www.openstack.org

ReferenceDocumentation page

http://docs.openstack.org

Blueprints of documentshttps://blueprints.launchpad.net/ openstack-manuals

Bugs of documentshttp://bugs.launchpad.net/openstack-manuals

Main page for openstack-manuals translation in Transifexhttps://www.transifex.net/projects/p/openstack-manuals-i18n/

OpenStack Document Translation Guidehttps://gist.github.com/3037139

Address of Chinese Openstack manuals (as temporary)http://1.openstackcn.sinaapp.com/?page_id=8