SlideShare ist ein Scribd-Unternehmen logo
1 von 34
Downloaden Sie, um offline zu lesen
Open writing-cloud-collab
November 2012
Open Writing !
For Apache CloudStack
(Incubating)
We’ll Cover:
Where We Are
 Our doc website
 Our modular doc repo
 Community participation
How We Do That
 Wiki for doc process docs
 Docbook + Publican for authoring
 Reviewboard for reviews
 Jira for doc bugs
 Jenkins for continuous doc builds
 IRC and lists for discussions
 Transifex for localization
How We Got Here
 Joining Apache
 From unstructured to modular source
 Why Publican? And other design decisions
How You Can Do That
 Becoming a doc contributor
Where We Are:
Basically Where We Are
• Doc website:
incubator.apache.org/cloudstack/docs/
Old doc website: docs.cloudstack.org (soon to redirect)
• Doc source:
git-wip-us.apache.org/repos/asf/incubator-cloudstack.git
• Doc team:
cwiki.apache.org/confluence/display/CLOUDSTACK/Documentation+Team
• Mailing list:
cloudstack-dev@incubator.apache.org
Where We Are:
Apache CloudStack Doc Website
Where We Are:
Pre-Apache CloudStack Doc Website
Where We Are:
Doc Source Code Repo
How We Got Here:
CloudStack is Donated to Apache
• In April 2012, Citrix Systems Inc. donated CloudStack code and
documentation to the Apache Software Foundation, and CloudStack entered
the Apache incubation process, the first step towards becoming a full-fledged
Apache project
• CloudStack already had lots of published technical documentation, mostly as
downloadable PDFs with source in Microsoft Word
• Citrix tech pubs team aimed to donate the documentation in a way that would
enable open-source contribution and align with open-source practices
How We Got Here:
From Unstructured to Modular Source
• Docbook XML: community preferred this 100%. Familiar to most members. Discussion brief!
• How to get from MS Word to Docbook XML? Given <400 pages of docs: by cut and paste.
• Advantages of non-automation:
– Leave cruft behind, update old sections, copyedit. Add only good stuff to your repo
– Improve doc design and modularity along the way
– Always have a buildable doc set: skip the intermediate stage of semi-converted output
that awaits tweaking
• Some tools we considered and rejected:
– ooo2sdbk, aka Bellot's Convertisseur: Seems to require a lot of customization; and is in French
– pcwTextExportr: Tried, didn’t work
– OpenOffice "save as Docbook XML" feature, requires you to download XSLT & find instructions for XML filter:
Download links = broken
– YAWC: “no longer provide support” = likely converts to an outdated Docbook format
– Hire a format conversion service
– Automate using OOo SDK
How We Got Here:
Setting Up the Doc Repo
• git
• No decision to make here, it’s the same as used for the project’s code
• Discussion was required: standalone doc repo, or directory within code repo?
• Project community decided to keep docs and code in one repo. Advantages cited:
– Easier to find the doc source
– More likely to remember to check in docs with code
How We Do That:
Documentation Process Docs
• We provide how-to’s and other process docs for documentation contributors at:
cwiki.apache.org/confluence/display/CLOUDSTACK/Documentation+Team
How We Do That:
Modular Docbook XML Source Files
• We make each heading a separate XML file; about one “page” per file
• All files are in one directory; no subdirectories dividing the files into “books”
• 500 files total as of November 2012
Advantages of Modular Docbook Files:
• Reuse
• Small files = easier to distribute work
• Easier to pass review with smaller commits
• Dynamically modify text with conditionals and variables
• Source control
How We Do That:
Modular Docbook XML Source Files
Example file for a single section: whatis.xml
(Not shown: standard XML header, entity file declaration, and Apache license)
<section id="whatis">
<title>What Is &PRODUCT;?</title>
<para>&PRODUCT; is an open source software platform that pools computing resources to build public, private, and
hybrid Infrastructure as a Service (IaaS) clouds. &PRODUCT; manages the network, storage, and compute nodes that make
up a cloud infrastructure. Use &PRODUCT; to deploy, manage, and configure cloud computing environments.</para>
<para>Typical users are service providers and enterprises. With &PRODUCT;, you can:</para>
<itemizedlist>
<listitem>
<para>Set up an on-demand, elastic cloud computing service. Service providers can sell self service
virtual machine instances, storage volumes, and networking configurations over the Internet.</para></listitem>
<listitem>
<para>Set up an on-premise private cloud for use by employees. Rather than managing virtual machines in
the same way as physical machines, with &PRODUCT; an enterprise can offer self-service virtual machines to users
without involving IT departments.</para></listitem>
</itemizedlist>
<mediaobject>
<imageobject>
<imagedata fileref="./images/1000-foot-view.png" />
</imageobject>
<textobject><phrase>1000-foot-view.png: Overview of &PRODUCT;</phrase></textobject>
</mediaobject>
</section>
How We Do That:
Modular Docbook XML Source Files
Example file: whatis.xml inside a larger section, aka chapter
(Not shown: standard XML header, entity file declaration, and Apache license)
<chapter id="concepts">
<title>Concepts</title>
<xi:include href="whatis.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="feature-overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="deployment-arch-overview.xml xmlns:xi="http://www.w3.org/2001/XInclude" />
...
</chapter>
How We Do That:
Modular Docbook XML Source Files
Example of reuse: concepts.xml included in two book files
Admin_Guide.xml:
<book>
<bookinfo id="cloudstack_admin">
<title>&PRODUCT; Administrator's Guide</title>
...
<xi:include href="concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="accounts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
...
</book>
Installation_Guide.xml:
<book>
<bookinfo id="book-installation">
<title>&PRODUCT; Installation Guide</title>
...
<xi:include href="concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
...
</book>
How We Do That:
Publican
What is Publican?
• An open-source tool hosted by Fedora: fedorahosted.org/publican/
• Easy to set up
• Applies brands to “skin" content
• Can use conditional tags
• Generates a variety of output formats, and we use quite a few of them
• Generates .po files for translators
• User guide:
jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/index.html
How We Do That:
Publican
How does it work?
• A required set of files in a directory structure
• Config file
• Command line
• Output
• Debugging
• jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/index.html
How We Do That:
Publican
Example Publican directories
cloudstack/docs
adminguide.cfg (Configuration file for building Admin_Guide.xml)
installation.cfg (Configuration file for building Installation_Guide.xml)
README.txt
/en-US (Input files in Docbook)
about-hosts.xml
accounts.xml
Admin_Guide.xml
concepts.xml
Installation_Guide.xml
whatis.xml
...
/tmp (Output files)
/en-US
/html
/pdf
How We Do That:
Publican
Install Publican on Ubuntu
> sudo apt-get update
> sudo apt-get install fop publican
How We Do That:
Publican
Example config file
xml_lang: en-US
type: Book
docname: Installation_Guide
brand: cloudstack
chunk_first: 1
chunk_section_depth: 1
condition: install
Output type. Publican can also do articles, etc.
Publican looks for an XML file with this name
and uses that as the main book file
The product logo, CSS styles, copyright text,
nav button images, etc. are set in the brand
Chunk settings control when Publican starts a
new HTML output file
Conditional text marked with any other label
will be excluded from the output
How We Do That:
Publican
Example command line and output
> Publican build --langs en-US --formats html,pdf --config installation.cfg
Setting up en-US
Processing file tmp/en-US/xml_tmp/about-hosts.xml -> tmp/en-US/xml/about-hosts.xml
...
*WARNING: Questionable tag found: inlinegraphic
This tag breaks section 508 accessibility standards and makes translation extremely
difficult.
...
Processing file tmp/en-US/xml_tmp/zone-add.xml -> tmp/en-US/xml/zone-add.xml
Beginning work on en-US
Starting html
Writing whatis.html for section(whatis)
...
Writing index.html for book
Finished html
How We Do That:
Publican
Example: Debugging an error
Publican gives useful debugging output. For example, if you try to include whatis.xml twice in the same book:
Installation_Guide.xml:6: validity error : ID whatis already defined
The ID “whatis” is defined in the <section> tag at the top of the file whatis.xml:
<section id="whatis">
Each ID must be unique, so Publican won’t build this book. If you look at Installation_Guide.xml, after some
investigation you will see how whatis.xml is included twice: once on its own, and once inside concepts.xml.
<book>
<bookinfo id="book-installation">
<title>&PRODUCT; Installation Guide</title>
...
<xi:include href="whatis.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
...
How We Do That:
Documentation Reviews
How We Do That:
Jira for Doc Bugs
cwiki.apache.org/confluence/display/CLOUDSTACK/How+to+File+a+Documentation+Bug
How We Do That:
Jenkins for Continuous Doc Builds
• jenkins.cloudstack.org
• Trigger a build whenever code changes or at another configurable interval
Advantages:
• Continuously test the doc build, find errors quickly
• Continuously update the published docs
• Receive notifications
How We Do That:
Jenkins for Continuous Doc Builds
How We Do That:
Jenkins for Continuous Doc Builds
How We Do That/How You Can Do It Too:
Open-source Documentation Community
• Publicizing the opportunity to contribute to documentation
• Communication channels
– Mailing lists:
cloudstack-dev@incubator.apache.org
cloudstack-users@incubator.apache.org
– IRC chat: #cloudstack on irc.freenode.net
– Facebook: www.facebook.com/groups/cloudstack/
• Participating in discussions in a group known for frank opinions stated boldly
How You Can Do That:
Documentation Contributor’s How-To
• How-tos for contributors, status, plans, and other notes are all written down here:
cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+Documentation+Contributors+Overview
• Documentation needs and proposals are discussed on cloudstack-dev@incubator.apache.org
• Volunteer to write something by assigning a bug to yourself at
issues.apache.org/jira/browse/CLOUDSTACK
• Documentation reviews through Apache Review Board: reviews.apache.org/
– Submit new content as patches
– Get review comments and fix them, until a reviewer clicks Ship It!
– Apply the patch and update the review status to Submitted
• Style guide, required signoffs, or other formal process: Aside from the standard Apache CLA,
this is not in place yet, if ever. Just write!
• Another way to contribute: File doc bugs! Here’s how:
cwiki.apache.org/confluence/display/CLOUDSTACK/How+to+File+a+Documentation+Bug
How You Can Do That:
Documentation Sprints
• Publicized on the mailing list
• Can be in-person gathering, IRC session, or distributed network of participants
• Limited time period to ensure focus
• Signup sheets and instructions for participants are in the project wiki at
cwiki.apache.org/confluence/display/CLOUDSTACK/Doc+Sprints
• Any contributor can start a Sprint!
Join the community!
• Why?
ᵒ Learn the coolest technologies shaping the next decade
ᵒ Be part of a passionate community working at ground-breaking speed
ᵒ Solve cool real-world problems
ᵒ For the love of open source
ᵒ If you want to rise and shine
• Still don’t believe us – Let the numbers speak
ᵒ 30k active community members in 8 months, ~100 IRC users
ᵒ Exponentially growing dev/user community discussions
ᵒ Apache is the industry standard for 10+ years in OSS foundations, 100+ projects,
800 developers
ᵒ Well known projects: Apache webserver, Tomcat, Hadoop, Cassandra
Apache CloudStack Status
• In Incubation since April 2012
• PPMC and Mentors set up in April
• Code migrated to Apache git
• Migration underway from cloudstack.org:
– Website, now incubator.apache.org/cloudstack/
– Jira (bugs), now issues.apache.org/jira/browse/CLOUDSTACK
– Wiki (internal docs), now cwiki.apache.org/confluence/display/CLOUDSTACK/
• New committers, partners, developers every week
• Apache CloudStack 4.0: First ASF community release, Nov 2012
• Active development community
More Resources
incubator.apache.org/cloudstack/
http://www.youtube.com/user/cloudstack
November 2012
Thank You

Weitere ähnliche Inhalte

Was ist angesagt?

Oracle UCM: Web Site Performance Tuning
Oracle UCM: Web Site Performance TuningOracle UCM: Web Site Performance Tuning
Oracle UCM: Web Site Performance TuningBrian Huff
 
DSpace 4.2 Transmission: Import/Export
DSpace 4.2 Transmission: Import/ExportDSpace 4.2 Transmission: Import/Export
DSpace 4.2 Transmission: Import/ExportDuraSpace
 
Configuration Management in Drupal 8: A preview (DrupalCamp Alpe Adria 2014)
Configuration Management in Drupal 8: A preview (DrupalCamp Alpe Adria 2014)Configuration Management in Drupal 8: A preview (DrupalCamp Alpe Adria 2014)
Configuration Management in Drupal 8: A preview (DrupalCamp Alpe Adria 2014)Nuvole
 
Introduction to Module Development (Drupal 7)
Introduction to Module Development (Drupal 7)Introduction to Module Development (Drupal 7)
Introduction to Module Development (Drupal 7)April Sides
 
REST meets Semantic Web
REST meets Semantic WebREST meets Semantic Web
REST meets Semantic WebSteve Speicher
 
Automating Drupal Development: Makefiles, features and beyond
Automating Drupal Development: Makefiles, features and beyondAutomating Drupal Development: Makefiles, features and beyond
Automating Drupal Development: Makefiles, features and beyondNuvole
 
Drupal in 30 Minutes
Drupal in 30 MinutesDrupal in 30 Minutes
Drupal in 30 MinutesRobert Carr
 
DrupalCampLA 2011: Drupal backend-performance
DrupalCampLA 2011: Drupal backend-performanceDrupalCampLA 2011: Drupal backend-performance
DrupalCampLA 2011: Drupal backend-performanceAshok Modi
 
Devday 2014 using_afs_in_your_cloud_app
Devday 2014 using_afs_in_your_cloud_appDevday 2014 using_afs_in_your_cloud_app
Devday 2014 using_afs_in_your_cloud_appMihail Mateev
 
DSpace Today and Tomorrow
DSpace Today and TomorrowDSpace Today and Tomorrow
DSpace Today and TomorrowBram Luyten
 
DSpace Tutorial : Open Source Digital Library
DSpace Tutorial : Open Source Digital LibraryDSpace Tutorial : Open Source Digital Library
DSpace Tutorial : Open Source Digital Libraryrajivkumarmca
 
Migration from Legacy CMS to Drupal
Migration from Legacy CMS to DrupalMigration from Legacy CMS to Drupal
Migration from Legacy CMS to DrupalRachel Jaro
 
AWS Summit Berlin 2012 Talk on Web Data Commons
AWS Summit Berlin 2012 Talk on Web Data CommonsAWS Summit Berlin 2012 Talk on Web Data Commons
AWS Summit Berlin 2012 Talk on Web Data CommonsHannes Mühleisen
 
Configuration Management in Drupal 8: A preview (DrupalDays Milano 2014)
Configuration Management in Drupal 8: A preview (DrupalDays Milano 2014)Configuration Management in Drupal 8: A preview (DrupalDays Milano 2014)
Configuration Management in Drupal 8: A preview (DrupalDays Milano 2014)Nuvole
 
DrupalCampLA 2011 - Drupal frontend-optimizing
DrupalCampLA 2011 - Drupal frontend-optimizingDrupalCampLA 2011 - Drupal frontend-optimizing
DrupalCampLA 2011 - Drupal frontend-optimizingAshok Modi
 
NOMAD ENTERPRISE & WAN CACHING APPLIANCES NETWORK OPTIMIZATION IN A CONFIGURA...
NOMAD ENTERPRISE & WAN CACHING APPLIANCES NETWORK OPTIMIZATION IN A CONFIGURA...NOMAD ENTERPRISE & WAN CACHING APPLIANCES NETWORK OPTIMIZATION IN A CONFIGURA...
NOMAD ENTERPRISE & WAN CACHING APPLIANCES NETWORK OPTIMIZATION IN A CONFIGURA...1E: Software Lifecycle Automation
 
Compact, Compress, De-Duplicate (DAOS)
Compact, Compress, De-Duplicate (DAOS)Compact, Compress, De-Duplicate (DAOS)
Compact, Compress, De-Duplicate (DAOS)Ulrich Krause
 
Web Performance First Aid
Web Performance First AidWeb Performance First Aid
Web Performance First AidAlan Seiden
 
Access Data from XPages with the Relational Controls
Access Data from XPages with the Relational ControlsAccess Data from XPages with the Relational Controls
Access Data from XPages with the Relational ControlsTeamstudio
 

Was ist angesagt? (20)

Oracle UCM: Web Site Performance Tuning
Oracle UCM: Web Site Performance TuningOracle UCM: Web Site Performance Tuning
Oracle UCM: Web Site Performance Tuning
 
DSpace 4.2 Transmission: Import/Export
DSpace 4.2 Transmission: Import/ExportDSpace 4.2 Transmission: Import/Export
DSpace 4.2 Transmission: Import/Export
 
Configuration Management in Drupal 8: A preview (DrupalCamp Alpe Adria 2014)
Configuration Management in Drupal 8: A preview (DrupalCamp Alpe Adria 2014)Configuration Management in Drupal 8: A preview (DrupalCamp Alpe Adria 2014)
Configuration Management in Drupal 8: A preview (DrupalCamp Alpe Adria 2014)
 
Introduction to Module Development (Drupal 7)
Introduction to Module Development (Drupal 7)Introduction to Module Development (Drupal 7)
Introduction to Module Development (Drupal 7)
 
REST meets Semantic Web
REST meets Semantic WebREST meets Semantic Web
REST meets Semantic Web
 
Automating Drupal Development: Makefiles, features and beyond
Automating Drupal Development: Makefiles, features and beyondAutomating Drupal Development: Makefiles, features and beyond
Automating Drupal Development: Makefiles, features and beyond
 
Drupal in 30 Minutes
Drupal in 30 MinutesDrupal in 30 Minutes
Drupal in 30 Minutes
 
DrupalCampLA 2011: Drupal backend-performance
DrupalCampLA 2011: Drupal backend-performanceDrupalCampLA 2011: Drupal backend-performance
DrupalCampLA 2011: Drupal backend-performance
 
Devday 2014 using_afs_in_your_cloud_app
Devday 2014 using_afs_in_your_cloud_appDevday 2014 using_afs_in_your_cloud_app
Devday 2014 using_afs_in_your_cloud_app
 
DSpace Today and Tomorrow
DSpace Today and TomorrowDSpace Today and Tomorrow
DSpace Today and Tomorrow
 
DSpace Tutorial : Open Source Digital Library
DSpace Tutorial : Open Source Digital LibraryDSpace Tutorial : Open Source Digital Library
DSpace Tutorial : Open Source Digital Library
 
Migration from Legacy CMS to Drupal
Migration from Legacy CMS to DrupalMigration from Legacy CMS to Drupal
Migration from Legacy CMS to Drupal
 
AWS Summit Berlin 2012 Talk on Web Data Commons
AWS Summit Berlin 2012 Talk on Web Data CommonsAWS Summit Berlin 2012 Talk on Web Data Commons
AWS Summit Berlin 2012 Talk on Web Data Commons
 
Configuration Management in Drupal 8: A preview (DrupalDays Milano 2014)
Configuration Management in Drupal 8: A preview (DrupalDays Milano 2014)Configuration Management in Drupal 8: A preview (DrupalDays Milano 2014)
Configuration Management in Drupal 8: A preview (DrupalDays Milano 2014)
 
DrupalCampLA 2011 - Drupal frontend-optimizing
DrupalCampLA 2011 - Drupal frontend-optimizingDrupalCampLA 2011 - Drupal frontend-optimizing
DrupalCampLA 2011 - Drupal frontend-optimizing
 
NOMAD ENTERPRISE & WAN CACHING APPLIANCES NETWORK OPTIMIZATION IN A CONFIGURA...
NOMAD ENTERPRISE & WAN CACHING APPLIANCES NETWORK OPTIMIZATION IN A CONFIGURA...NOMAD ENTERPRISE & WAN CACHING APPLIANCES NETWORK OPTIMIZATION IN A CONFIGURA...
NOMAD ENTERPRISE & WAN CACHING APPLIANCES NETWORK OPTIMIZATION IN A CONFIGURA...
 
Domino testing presentation
Domino testing presentationDomino testing presentation
Domino testing presentation
 
Compact, Compress, De-Duplicate (DAOS)
Compact, Compress, De-Duplicate (DAOS)Compact, Compress, De-Duplicate (DAOS)
Compact, Compress, De-Duplicate (DAOS)
 
Web Performance First Aid
Web Performance First AidWeb Performance First Aid
Web Performance First Aid
 
Access Data from XPages with the Relational Controls
Access Data from XPages with the Relational ControlsAccess Data from XPages with the Relational Controls
Access Data from XPages with the Relational Controls
 

Andere mochten auch (6)

Wemta flipped classroom1
Wemta flipped classroom1Wemta flipped classroom1
Wemta flipped classroom1
 
Monitorowanie aplikacji z System Center 2012
Monitorowanie aplikacji z System Center 2012Monitorowanie aplikacji z System Center 2012
Monitorowanie aplikacji z System Center 2012
 
Ppt cihuyyy
Ppt cihuyyyPpt cihuyyy
Ppt cihuyyy
 
Ch 02 instructor version
Ch 02 instructor versionCh 02 instructor version
Ch 02 instructor version
 
икт
иктикт
икт
 
Companies
CompaniesCompanies
Companies
 

Ähnlich wie Open writing-cloud-collab

[DanNotes] XPages - Beyound the Basics
[DanNotes] XPages - Beyound the Basics[DanNotes] XPages - Beyound the Basics
[DanNotes] XPages - Beyound the BasicsUlrich Krause
 
Build Automation of PHP Applications
Build Automation of PHP ApplicationsBuild Automation of PHP Applications
Build Automation of PHP ApplicationsPavan Kumar N
 
XPages -Beyond the Basics
XPages -Beyond the BasicsXPages -Beyond the Basics
XPages -Beyond the BasicsUlrich Krause
 
Challenges of Simple Documents: When Basic isn't so Basic - Cassandra Targett...
Challenges of Simple Documents: When Basic isn't so Basic - Cassandra Targett...Challenges of Simple Documents: When Basic isn't so Basic - Cassandra Targett...
Challenges of Simple Documents: When Basic isn't so Basic - Cassandra Targett...Lucidworks
 
UKLUG 2012 - XPages, Beyond the basics
UKLUG 2012 - XPages, Beyond the basicsUKLUG 2012 - XPages, Beyond the basics
UKLUG 2012 - XPages, Beyond the basicsUlrich Krause
 
Drupal distributions - how to build them
Drupal distributions - how to build themDrupal distributions - how to build them
Drupal distributions - how to build themDick Olsson
 
Auslug 2011 customising ibm connections
Auslug 2011 customising ibm connectionsAuslug 2011 customising ibm connections
Auslug 2011 customising ibm connectionsAdam Brown
 
Top 8 Improvements in Drupal 8
Top 8 Improvements in Drupal 8Top 8 Improvements in Drupal 8
Top 8 Improvements in Drupal 8Angela Byron
 
10135 a 02
10135 a 0210135 a 02
10135 a 02Bố Su
 
Deploying DAOS and ID Vault
Deploying DAOS and ID VaultDeploying DAOS and ID Vault
Deploying DAOS and ID VaultLuis Guirigay
 
Expanding XPages with Bootstrap Plugins for Ultimate Usability
Expanding XPages with Bootstrap Plugins for Ultimate UsabilityExpanding XPages with Bootstrap Plugins for Ultimate Usability
Expanding XPages with Bootstrap Plugins for Ultimate UsabilityTeamstudio
 
APACHE
APACHEAPACHE
APACHEARJUN
 
Corporate-informatica-training-in-mumbai
Corporate-informatica-training-in-mumbaiCorporate-informatica-training-in-mumbai
Corporate-informatica-training-in-mumbaiUnmesh Baile
 
Corporate-informatica-training-in-mumbai
Corporate-informatica-training-in-mumbaiCorporate-informatica-training-in-mumbai
Corporate-informatica-training-in-mumbaiUnmesh Baile
 
Rapidly prototyping web applications using BackPress
Rapidly prototyping web applications using BackPressRapidly prototyping web applications using BackPress
Rapidly prototyping web applications using BackPressNathaniel Taintor
 
Beginner's guide to drupal
Beginner's guide to drupalBeginner's guide to drupal
Beginner's guide to drupalmayank.grd
 
Presentation on Japanese doc sprint
Presentation on Japanese doc sprintPresentation on Japanese doc sprint
Presentation on Japanese doc sprintGo Chiba
 

Ähnlich wie Open writing-cloud-collab (20)

[DanNotes] XPages - Beyound the Basics
[DanNotes] XPages - Beyound the Basics[DanNotes] XPages - Beyound the Basics
[DanNotes] XPages - Beyound the Basics
 
Build Automation of PHP Applications
Build Automation of PHP ApplicationsBuild Automation of PHP Applications
Build Automation of PHP Applications
 
XPages -Beyond the Basics
XPages -Beyond the BasicsXPages -Beyond the Basics
XPages -Beyond the Basics
 
Challenges of Simple Documents: When Basic isn't so Basic - Cassandra Targett...
Challenges of Simple Documents: When Basic isn't so Basic - Cassandra Targett...Challenges of Simple Documents: When Basic isn't so Basic - Cassandra Targett...
Challenges of Simple Documents: When Basic isn't so Basic - Cassandra Targett...
 
UKLUG 2012 - XPages, Beyond the basics
UKLUG 2012 - XPages, Beyond the basicsUKLUG 2012 - XPages, Beyond the basics
UKLUG 2012 - XPages, Beyond the basics
 
vitepress-en.pdf
vitepress-en.pdfvitepress-en.pdf
vitepress-en.pdf
 
Drupal distributions - how to build them
Drupal distributions - how to build themDrupal distributions - how to build them
Drupal distributions - how to build them
 
Auslug 2011 customising ibm connections
Auslug 2011 customising ibm connectionsAuslug 2011 customising ibm connections
Auslug 2011 customising ibm connections
 
Top 8 Improvements in Drupal 8
Top 8 Improvements in Drupal 8Top 8 Improvements in Drupal 8
Top 8 Improvements in Drupal 8
 
Scaling PHP apps
Scaling PHP appsScaling PHP apps
Scaling PHP apps
 
10135 a 02
10135 a 0210135 a 02
10135 a 02
 
Deploying DAOS and ID Vault
Deploying DAOS and ID VaultDeploying DAOS and ID Vault
Deploying DAOS and ID Vault
 
Expanding XPages with Bootstrap Plugins for Ultimate Usability
Expanding XPages with Bootstrap Plugins for Ultimate UsabilityExpanding XPages with Bootstrap Plugins for Ultimate Usability
Expanding XPages with Bootstrap Plugins for Ultimate Usability
 
APACHE
APACHEAPACHE
APACHE
 
Corporate-informatica-training-in-mumbai
Corporate-informatica-training-in-mumbaiCorporate-informatica-training-in-mumbai
Corporate-informatica-training-in-mumbai
 
Corporate-informatica-training-in-mumbai
Corporate-informatica-training-in-mumbaiCorporate-informatica-training-in-mumbai
Corporate-informatica-training-in-mumbai
 
Rapidly prototyping web applications using BackPress
Rapidly prototyping web applications using BackPressRapidly prototyping web applications using BackPress
Rapidly prototyping web applications using BackPress
 
Beginner's guide to drupal
Beginner's guide to drupalBeginner's guide to drupal
Beginner's guide to drupal
 
Fewd week1 slides
Fewd week1 slidesFewd week1 slides
Fewd week1 slides
 
Presentation on Japanese doc sprint
Presentation on Japanese doc sprintPresentation on Japanese doc sprint
Presentation on Japanese doc sprint
 

Open writing-cloud-collab

  • 2. November 2012 Open Writing ! For Apache CloudStack (Incubating)
  • 3. We’ll Cover: Where We Are  Our doc website  Our modular doc repo  Community participation How We Do That  Wiki for doc process docs  Docbook + Publican for authoring  Reviewboard for reviews  Jira for doc bugs  Jenkins for continuous doc builds  IRC and lists for discussions  Transifex for localization How We Got Here  Joining Apache  From unstructured to modular source  Why Publican? And other design decisions How You Can Do That  Becoming a doc contributor
  • 4. Where We Are: Basically Where We Are • Doc website: incubator.apache.org/cloudstack/docs/ Old doc website: docs.cloudstack.org (soon to redirect) • Doc source: git-wip-us.apache.org/repos/asf/incubator-cloudstack.git • Doc team: cwiki.apache.org/confluence/display/CLOUDSTACK/Documentation+Team • Mailing list: cloudstack-dev@incubator.apache.org
  • 5. Where We Are: Apache CloudStack Doc Website
  • 6. Where We Are: Pre-Apache CloudStack Doc Website
  • 7. Where We Are: Doc Source Code Repo
  • 8. How We Got Here: CloudStack is Donated to Apache • In April 2012, Citrix Systems Inc. donated CloudStack code and documentation to the Apache Software Foundation, and CloudStack entered the Apache incubation process, the first step towards becoming a full-fledged Apache project • CloudStack already had lots of published technical documentation, mostly as downloadable PDFs with source in Microsoft Word • Citrix tech pubs team aimed to donate the documentation in a way that would enable open-source contribution and align with open-source practices
  • 9. How We Got Here: From Unstructured to Modular Source • Docbook XML: community preferred this 100%. Familiar to most members. Discussion brief! • How to get from MS Word to Docbook XML? Given <400 pages of docs: by cut and paste. • Advantages of non-automation: – Leave cruft behind, update old sections, copyedit. Add only good stuff to your repo – Improve doc design and modularity along the way – Always have a buildable doc set: skip the intermediate stage of semi-converted output that awaits tweaking • Some tools we considered and rejected: – ooo2sdbk, aka Bellot's Convertisseur: Seems to require a lot of customization; and is in French – pcwTextExportr: Tried, didn’t work – OpenOffice "save as Docbook XML" feature, requires you to download XSLT & find instructions for XML filter: Download links = broken – YAWC: “no longer provide support” = likely converts to an outdated Docbook format – Hire a format conversion service – Automate using OOo SDK
  • 10. How We Got Here: Setting Up the Doc Repo • git • No decision to make here, it’s the same as used for the project’s code • Discussion was required: standalone doc repo, or directory within code repo? • Project community decided to keep docs and code in one repo. Advantages cited: – Easier to find the doc source – More likely to remember to check in docs with code
  • 11. How We Do That: Documentation Process Docs • We provide how-to’s and other process docs for documentation contributors at: cwiki.apache.org/confluence/display/CLOUDSTACK/Documentation+Team
  • 12. How We Do That: Modular Docbook XML Source Files • We make each heading a separate XML file; about one “page” per file • All files are in one directory; no subdirectories dividing the files into “books” • 500 files total as of November 2012 Advantages of Modular Docbook Files: • Reuse • Small files = easier to distribute work • Easier to pass review with smaller commits • Dynamically modify text with conditionals and variables • Source control
  • 13. How We Do That: Modular Docbook XML Source Files Example file for a single section: whatis.xml (Not shown: standard XML header, entity file declaration, and Apache license) <section id="whatis"> <title>What Is &PRODUCT;?</title> <para>&PRODUCT; is an open source software platform that pools computing resources to build public, private, and hybrid Infrastructure as a Service (IaaS) clouds. &PRODUCT; manages the network, storage, and compute nodes that make up a cloud infrastructure. Use &PRODUCT; to deploy, manage, and configure cloud computing environments.</para> <para>Typical users are service providers and enterprises. With &PRODUCT;, you can:</para> <itemizedlist> <listitem> <para>Set up an on-demand, elastic cloud computing service. Service providers can sell self service virtual machine instances, storage volumes, and networking configurations over the Internet.</para></listitem> <listitem> <para>Set up an on-premise private cloud for use by employees. Rather than managing virtual machines in the same way as physical machines, with &PRODUCT; an enterprise can offer self-service virtual machines to users without involving IT departments.</para></listitem> </itemizedlist> <mediaobject> <imageobject> <imagedata fileref="./images/1000-foot-view.png" /> </imageobject> <textobject><phrase>1000-foot-view.png: Overview of &PRODUCT;</phrase></textobject> </mediaobject> </section>
  • 14. How We Do That: Modular Docbook XML Source Files Example file: whatis.xml inside a larger section, aka chapter (Not shown: standard XML header, entity file declaration, and Apache license) <chapter id="concepts"> <title>Concepts</title> <xi:include href="whatis.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="feature-overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="deployment-arch-overview.xml xmlns:xi="http://www.w3.org/2001/XInclude" /> ... </chapter>
  • 15. How We Do That: Modular Docbook XML Source Files Example of reuse: concepts.xml included in two book files Admin_Guide.xml: <book> <bookinfo id="cloudstack_admin"> <title>&PRODUCT; Administrator's Guide</title> ... <xi:include href="concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="accounts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> ... </book> Installation_Guide.xml: <book> <bookinfo id="book-installation"> <title>&PRODUCT; Installation Guide</title> ... <xi:include href="concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> ... </book>
  • 16. How We Do That: Publican What is Publican? • An open-source tool hosted by Fedora: fedorahosted.org/publican/ • Easy to set up • Applies brands to “skin" content • Can use conditional tags • Generates a variety of output formats, and we use quite a few of them • Generates .po files for translators • User guide: jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/index.html
  • 17. How We Do That: Publican How does it work? • A required set of files in a directory structure • Config file • Command line • Output • Debugging • jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/index.html
  • 18. How We Do That: Publican Example Publican directories cloudstack/docs adminguide.cfg (Configuration file for building Admin_Guide.xml) installation.cfg (Configuration file for building Installation_Guide.xml) README.txt /en-US (Input files in Docbook) about-hosts.xml accounts.xml Admin_Guide.xml concepts.xml Installation_Guide.xml whatis.xml ... /tmp (Output files) /en-US /html /pdf
  • 19. How We Do That: Publican Install Publican on Ubuntu > sudo apt-get update > sudo apt-get install fop publican
  • 20. How We Do That: Publican Example config file xml_lang: en-US type: Book docname: Installation_Guide brand: cloudstack chunk_first: 1 chunk_section_depth: 1 condition: install Output type. Publican can also do articles, etc. Publican looks for an XML file with this name and uses that as the main book file The product logo, CSS styles, copyright text, nav button images, etc. are set in the brand Chunk settings control when Publican starts a new HTML output file Conditional text marked with any other label will be excluded from the output
  • 21. How We Do That: Publican Example command line and output > Publican build --langs en-US --formats html,pdf --config installation.cfg Setting up en-US Processing file tmp/en-US/xml_tmp/about-hosts.xml -> tmp/en-US/xml/about-hosts.xml ... *WARNING: Questionable tag found: inlinegraphic This tag breaks section 508 accessibility standards and makes translation extremely difficult. ... Processing file tmp/en-US/xml_tmp/zone-add.xml -> tmp/en-US/xml/zone-add.xml Beginning work on en-US Starting html Writing whatis.html for section(whatis) ... Writing index.html for book Finished html
  • 22. How We Do That: Publican Example: Debugging an error Publican gives useful debugging output. For example, if you try to include whatis.xml twice in the same book: Installation_Guide.xml:6: validity error : ID whatis already defined The ID “whatis” is defined in the <section> tag at the top of the file whatis.xml: <section id="whatis"> Each ID must be unique, so Publican won’t build this book. If you look at Installation_Guide.xml, after some investigation you will see how whatis.xml is included twice: once on its own, and once inside concepts.xml. <book> <bookinfo id="book-installation"> <title>&PRODUCT; Installation Guide</title> ... <xi:include href="whatis.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> ...
  • 23. How We Do That: Documentation Reviews
  • 24. How We Do That: Jira for Doc Bugs cwiki.apache.org/confluence/display/CLOUDSTACK/How+to+File+a+Documentation+Bug
  • 25. How We Do That: Jenkins for Continuous Doc Builds • jenkins.cloudstack.org • Trigger a build whenever code changes or at another configurable interval Advantages: • Continuously test the doc build, find errors quickly • Continuously update the published docs • Receive notifications
  • 26. How We Do That: Jenkins for Continuous Doc Builds
  • 27. How We Do That: Jenkins for Continuous Doc Builds
  • 28. How We Do That/How You Can Do It Too: Open-source Documentation Community • Publicizing the opportunity to contribute to documentation • Communication channels – Mailing lists: cloudstack-dev@incubator.apache.org cloudstack-users@incubator.apache.org – IRC chat: #cloudstack on irc.freenode.net – Facebook: www.facebook.com/groups/cloudstack/ • Participating in discussions in a group known for frank opinions stated boldly
  • 29. How You Can Do That: Documentation Contributor’s How-To • How-tos for contributors, status, plans, and other notes are all written down here: cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+Documentation+Contributors+Overview • Documentation needs and proposals are discussed on cloudstack-dev@incubator.apache.org • Volunteer to write something by assigning a bug to yourself at issues.apache.org/jira/browse/CLOUDSTACK • Documentation reviews through Apache Review Board: reviews.apache.org/ – Submit new content as patches – Get review comments and fix them, until a reviewer clicks Ship It! – Apply the patch and update the review status to Submitted • Style guide, required signoffs, or other formal process: Aside from the standard Apache CLA, this is not in place yet, if ever. Just write! • Another way to contribute: File doc bugs! Here’s how: cwiki.apache.org/confluence/display/CLOUDSTACK/How+to+File+a+Documentation+Bug
  • 30. How You Can Do That: Documentation Sprints • Publicized on the mailing list • Can be in-person gathering, IRC session, or distributed network of participants • Limited time period to ensure focus • Signup sheets and instructions for participants are in the project wiki at cwiki.apache.org/confluence/display/CLOUDSTACK/Doc+Sprints • Any contributor can start a Sprint!
  • 31. Join the community! • Why? ᵒ Learn the coolest technologies shaping the next decade ᵒ Be part of a passionate community working at ground-breaking speed ᵒ Solve cool real-world problems ᵒ For the love of open source ᵒ If you want to rise and shine • Still don’t believe us – Let the numbers speak ᵒ 30k active community members in 8 months, ~100 IRC users ᵒ Exponentially growing dev/user community discussions ᵒ Apache is the industry standard for 10+ years in OSS foundations, 100+ projects, 800 developers ᵒ Well known projects: Apache webserver, Tomcat, Hadoop, Cassandra
  • 32. Apache CloudStack Status • In Incubation since April 2012 • PPMC and Mentors set up in April • Code migrated to Apache git • Migration underway from cloudstack.org: – Website, now incubator.apache.org/cloudstack/ – Jira (bugs), now issues.apache.org/jira/browse/CLOUDSTACK – Wiki (internal docs), now cwiki.apache.org/confluence/display/CLOUDSTACK/ • New committers, partners, developers every week • Apache CloudStack 4.0: First ASF community release, Nov 2012 • Active development community