open writing! collaborative authoring for cloudstack documentation by jessica tomechak

34

Upload: buildacloud

Post on 30-Oct-2014

1.414 views

Category:

Technology


0 download

DESCRIPTION

Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

TRANSCRIPT

Page 1: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak
Page 2: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

November 2012

Open Writing !

For Apache CloudStack (Incubating)

Page 3: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 5: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

Where We Are:Apache CloudStack Doc Website

Page 6: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

Where We Are:Pre-Apache CloudStack Doc Website

Page 7: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

Where We Are:Doc Source Code Repo

Page 8: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 9: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 10: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 11: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 12: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 13: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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>

Page 14: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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>

Page 15: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

How We Do That:Modular Docbook XML Source FilesExample of reuse: concepts.xml included in two book filesAdmin_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>

Page 16: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 17: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 18: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

How We Do That:Publican

Example Publican directoriescloudstack/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

Page 19: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

How We Do That:Publican

Install Publican on Ubuntu

> sudo apt-get update

> sudo apt-get install fop publican

Page 20: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

How We Do That:Publican

Example config file

xml_lang: en-UStype: Bookdocname: Installation_Guidebrand: cloudstackchunk_first: 1chunk_section_depth: 1condition: 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

Page 21: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

How We Do That:Publican

Example command line and output

> Publican build --langs en-US --formats html,pdf --config installation.cfgSetting up en-USProcessing file tmp/en-US/xml_tmp/about-hosts.xml -> tmp/en-US/xml/about-hosts.xml...*WARNING: Questionable tag found: inlinegraphicThis 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.xmlBeginning work on en-USStarting htmlWriting whatis.html for section(whatis)...Writing index.html for bookFinished html

Page 22: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

How We Do That:Publican

Example: Debugging an errorPublican 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" /> ...

Page 23: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

How We Do That:Documentation Reviews

Page 24: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

How We Do That:Jira for Doc Bugscwiki.apache.org/confluence/display/CLOUDSTACK/How+to+File+a+Documentation+Bug

Page 25: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 26: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

How We Do That:Jenkins for Continuous Doc Builds

Page 27: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

How We Do That:Jenkins for Continuous Doc Builds

Page 28: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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: [email protected] [email protected]

– 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

Page 29: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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 [email protected]• 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

Page 30: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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!

Page 31: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 32: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

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

Page 34: Open Writing! Collaborative Authoring for CloudStack Documentation by Jessica Tomechak

November 2012

Thank You