2012 OpenStack APAC Conference

11 Aug 2012

OpenStack
OpenStack Documentation and
Translation Management

OpenStack
guoyingc@cn.ibm.com

Anne Gentle
OpenStack
anne@openstack.org

2009 IBM Corporation


Agenda
OpenStack
Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Questions with Answers

www.openstack.org


Agenda
OpenStack
Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Questions with Answers

www.openstack.org


Web Page for Documentation
http://docs.openstack.org

www.openstack.org


Challenges of Community Documentation

Large amount of code

Grow quickly

Change frequently

Loose coupling

Manage document as code !

www.openstack.org

 :
Document Process: Design

Blueprints and discussion at Design Summit

Blueprints
https://blueprints.launchpad.net/openstack-manuals

Current blueprints found at https://blueprints.launchpad.net/

openstack-manuals

www.openstack.org


Document Process Development
API Github
Github repositories store admin guides and API guides
Jenkins
Unit tests with Jenkins
Gerrit
Patch review with Gerrit

www.openstack.org

 Bug
Document Process Bug tracking
Launchpad Bug
Manage bugs through Launchpad
Bug logging
Bug
Bug triaging
Bug
Bug assigning
Bug

www.openstack.org


Document Process Publishing
Jenkins
Automatically publish with Jenkins

www.openstack.org


Doc Team Composition
OpenStack
All OpenStack community members
OpenStack
One percenter = OpenStack-doc-core

Badge Wearers
AT&T
IBM
Nebula
Nicira
Nimbis Services
Nuage
Rackspace
RedHat

www.openstack.org

10


Statics
api.openstack.org 20 API
20+ Compute Extensions documented at api.openstack.org
66%
66% Site visitors stay instead of leaving
100
100 Doc patches and reviews a month
726 467 nova 259 swift

726 Configuration options: 467 for nova.conf, 259 for swift conf files
docs.openstack.org 10,000
10,000 Unique visitors a week at docs.openstack.org

www.openstack.org

11


Agenda
OpenStack
Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Questions with Answers

www.openstack.org

12


Challenges of Document Translation

Large amount of code

Grow quickly

Change frequently

Loose coupling

Manage document translation as code string translation!

www.openstack.org

13


Translation Process Slicing
Python DocBook PO
Slice DocBook into string segment with a Python script, and generate a PO
template
./tools/generatepot openstack-compute-admin

www.openstack.org

14


Translation Process Translating
Transifex

www.openstack.org

Manage translation by Transifex

Translation project & resources
Translation memory
Glossary

15


Translation Process Merging
Python DocBook
Merge the translated string into Docbook with a python script.
./tools/generatedocbook -l zh_CN -b openstack-compute-admin

www.openstack.org

16


Translation Process Uploading & Downloading

Transifex
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-apiprogramming/locale/openstack-api-programming.pot execute
tx push -s -r openstack-manuals-i18n.api-quick-start
tx pull -f -l zh_CN -r openstack-manuals-i18n.api-quick-start

www.openstack.org

17


Translation Process Change Management

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

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
www.openstack.org

18


Statics
OpenStack 7 Transifex 5550
7 books of OpenStack Manuals have been uploaded to Transifex, including 5550
items for translation.
6 Transifex 6
6 translation teams created in Transifex for 6 languages translation:

Chinese, Spanish, French, Japanese, Korean, Turkish (Turkey)

3
3 languages translation started
4% 4% - 1%
Chinese 4 %, Spanish 4 %, French 1 %

9
9 translators joined Chinese translation team

1 manual document finished Chinese translation

OpenStack API
OpenStack API Quick Start

www.openstack.org

19


Agenda
OpenStack
Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Questions with Answers

www.openstack.org

20


Sample Chinese Document Generation
Git OpenStack
Step 1: Check out the sources from Git repository
git clone https://github.com/daisy-ycguo/openstack-manuals-i18n.git

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

www.openstack.org

21


Sample Chinese Document Generation
DocBook DocBook
Step 3: Merge the translation segment back to DocBook
./tools/generatedocbook -l zh_CN -b api-quick-start

DocBook PDF HTML

Step 4: Generate PDF and HTML document
mvn generate-sources

www.openstack.org


Agenda
OpenStack
Status of OpenStack Document

Translation Management & Process

Samples of Translation Process

Questions with Answers

www.openstack.org

23

 openstack-core-docs

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

http://review.openstack.org openstack-manuals
Do lots of reviews at http://review.openstack.org for the openstackmanuals project.
Bug http://bugs.launchpad.net/openstackmanuals
Triage bugs and log doc bugs at
http://bugs.launchpad.net/openstack-manuals.
openstack-docs-core openstackcore-docs
Well discuss on the openstack-docs-core mailing list and then
invite you.

www.openstack.org

24


How should I find doc work that needs to be
done on a particular project?
http://bugs.launchpad.net/openstack-manuals
wishlist bug
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.
Bug
We also track few blueprints which may need someone to work on,
though doc bugs are probably the best first place to look

www.openstack.org

25


Who should do reviews of my document
changes?
Anne Gentle openstack-doc-core
bug

Anne Gentle, the doc coordinator, or anyone on the openstack-doccore 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.

www.openstack.org

26


How to join the translation team
www.transifex.net openstack
join team
Register an account at www.transifex.com firstly, and then go to
openstack-manuals translation page. After that, select your favorite
language and click join team at the top right corner.

Your request will be approved by the language coordinator.

www.openstack.org

27


How to get the latest translation documents
Git Transifex
DocBook Maven

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

www.openstack.org

28


Conclusion
OpenStack
Managing document as code is key to the success of OpenStack
documentation.
OpenStack
The translation is just started. I will need the support and participation
from all of you.
OpenStack
Your participation is warmly welcomed.
Anne Gentle
For any problems about documentation, please contact with Anne Gentle.

For any problems about translation, please contact with me.

www.openstack.org

29


Reference

Documentation page
http://docs.openstack.org

Blueprints of documents
https://blueprints.launchpad.net/ openstack-manuals

Bug
Bugs of documents
http://bugs.launchpad.net/openstack-manuals

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

OpenStack Document Translation Guide

https://gist.github.com/3037139

Address of Chinese Openstack manuals (as temporary)

http://1.openstackcn.sinaapp.com/?page_id=8
www.openstack.org