Difference between revisions of "Docs Bootcamp 2013"

Latest revision as of 16:02, 16 September 2013

What is it?

The OpenStack Docs Bootcamp offers a deep dive into the technical tools, workflows, and processes we use to create docs.openstack.org and api.openstack.org. Our goal is to give enough information that we'll create sustaining members who are core to OpenStack docs. The session isn't a book sprint and we don't expect huge output from the event itself, rather, we want to provide all the information we can so attendees can go back and become sustained contributors to the documentation efforts.

You can register to attend through this form.

Schedule

Monday

9:00 Opening welcome

9:15 OpenStack Docs Overview talk, Anne Gentle http://www.slideshare.net/annegentle/openstack-doc-overview-for-boot-camp

10:00: 45 mins (20-30 min talk, 20 minute lab) Doc build automation, Jim Blair

10:45 Break

11:00 45 mins (20-30 min talk, 20 minute lab) DocBook/Oxygen, David Cramer https://docs.google.com/presentation/d/1FIrOO7XqkLQhjfAD3o8V3NWqKbzgSuG9twsgTvfHpvk/edit#slide=id.p

12:00 Lunch

2:00 45 mins (20-30 min talk, 20 minute lab) How to Contribute to Docs, Nick Chase http://www.slideshare.net/mirantis/open-stackdocsbootcamp-howtocontribute-26186055

2:45 45 mins unconference

3:30 Break

4:00 45 mins unconference

4:45 Release to refresh before dinner

5:00 Go to dinner at Shoreline

Tuesday

9:00 Opening announcements

9:15 45 mins (20-30 min talk, 20 minute lab) WADL/API docs, Diane Fleming, https://wiki.openstack.org/wiki/File:Dianefleming_wadl_docbootcamp2013.pdf

10:00: 45 mins (20-30 min talk, 20 minute lab) Publican, Steven Gordon http://www.slideshare.net/sgordon2/publican

10:45 Break

11:00 45 mins (20-30 min talk, 20 minute lab) Install Docs, Shaun McCance

12:00 Lunch

1:00 45 mins Autodoc, Tom Fifield

1:45 45 mins unconference

2:00 45 mins unconference

2:45 Break

3:00 45 mins unconference

4:00 45 mins unconference

4:45 Break

5:00 45 mins unconference

5:45 Parting remarks

6:00 Go to dinner at Dish Dash

When is it?

Monday September 9 through Tuesday September 10, 2013

Where is it?

Mirantis is playing host in sunny Mountain View, California and will offer breakfast and lunch, thank you Mirantis! Rackspace is hosting the evening meals, thank you Rackspace!

Hotels near the Mirantis office:

Ramada 55 Fairchild Drive Mountain View, CA 800-252-1709

Quality Inn and Suites 5 Fairchild Drive Mountain View, CA (650) 934-0155

What's Expected

This is free training, but we would like you to get yourself there with these things ready to go.

Bring a laptop to work on. Mac, Ubuntu, Fedora, and RHEL are known to work. I haven't installed git review on Windows so I don't know if a Windows laptop would work.

Have the First Time Contributor process finalized, including signing the CLA and getting git review working. The steps are: Documentation/HowTo#First-time_Contributors

You should have current tools installed for working with documentation. This includes Maven and an editor of choice for editing DocBook or WADL documents. Any DocBook editor will do such as Oxygen or Emacs with validation or vi: https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing https://fedoraproject.org/wiki/Editing_DocBook_with_Vi If you don't have a floating license for Oxygen, use Emacs or vi.

Have git installed, know the basics of git and git review, and have clones of the modules you'll be working on locally. Here are the repos we'll be working on:

git clone http://github.com/openstack/openstack-manuals.git

git clone http://github.com/openstack/api-site.git

git clone http://github.com/openstack-infra/config.git

A demonstration of some Publican functionality is also planned as part of the activity around build tooling. If you wish to trial the demonstrated steps yourself it is recommended that you come with Publican 3.x installed. Publican 3.x is available in the standard repositories for these Linux distribution releases:

Fedora 18 and Fedora 19: https://admin.fedoraproject.org/updates/publican
Debian Jessie (testing): http://packages.debian.org/jessie/publican
Debian Sid (unstable): http://packages.debian.org/sid/publican
Ubuntu Saucy Salamander (Development): https://launchpad.net/ubuntu/+source/publican

Older releases of these distributions will likely provide Publican 2.8 or lower.

Mac OS/X users will need to follow the steps listed at https://fedorahosted.org/publican/wiki/Installing_OSX
Windows users can use the EXE installer to install Publican 3.0: http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Users_Guide/chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican-Windows_operating_systems

@@ Line 3: / Line 3: @@
 The OpenStack Docs Bootcamp offers a deep dive into the technical tools, workflows, and processes we use to create [http://docs.openstack.org docs.openstack.org] and [http://api.openstack.org api.openstack.org]. Our goal is to give enough information that we'll create sustaining members who are core to OpenStack docs. The session isn't a book sprint and we don't expect huge output from the event itself, rather, we want to provide all the information we can so attendees can go back and become sustained contributors to the documentation efforts.
-Schedule:
+You can register to attend through [https://docs.google.com/forms/d/1JwBinyXO1dQq_DbtRTrWeK1c7E8iwnGFZ1kgSrL4v7M/viewform this form].
+=== Schedule ===
+'''Monday'''
+:00 Opening welcome
+:15 OpenStack Docs Overview talk, Anne Gentle http://www.slideshare.net/annegentle/openstack-doc-overview-for-boot-camp
+:00: 45 mins (20-30 min talk, 20 minute lab) Doc build automation, Jim Blair
+:45 Break
+:00 45 mins (20-30 min talk, 20 minute lab) DocBook/Oxygen, David Cramer https://docs.google.com/presentation/d/1FIrOO7XqkLQhjfAD3o8V3NWqKbzgSuG9twsgTvfHpvk/edit#slide=id.p
+:00 Lunch
+:00 45 mins (20-30 min talk, 20 minute lab) How to Contribute to Docs, Nick Chase
+http://www.slideshare.net/mirantis/open-stackdocsbootcamp-howtocontribute-26186055
-DocBook (day one)
+:45 45 mins unconference
-Build/automation tooling (day one)
+:30 Break
-Operations/Admin/Install Docs (day two)
+:00 45 mins unconference
-API and User Docs including WADL (day two)
+:45 Release to refresh before dinner
-You can register to attend through [https://docs.google.com/forms/d/1JwBinyXO1dQq_DbtRTrWeK1c7E8iwnGFZ1kgSrL4v7M/viewform this form].
+:00 Go to dinner at Shoreline
+'''Tuesday'''
+:00 Opening announcements
+:15 45 mins (20-30 min talk, 20 minute lab) WADL/API docs, Diane Fleming, https://wiki.openstack.org/wiki/File:Dianefleming_wadl_docbootcamp2013.pdf
+:00: 45 mins (20-30 min talk, 20 minute lab) Publican, Steven Gordon http://www.slideshare.net/sgordon2/publican
+:45 Break
+:00 45 mins (20-30 min talk, 20 minute lab) Install Docs, Shaun McCance
+:00 Lunch
+:00 45 mins Autodoc, Tom Fifield
+:45 45 mins unconference
+:00 45 mins unconference
+:45 Break
+:00 45 mins unconference
+:00 45 mins unconference
+:45 Break
+:00 45 mins unconference
+:45 Parting remarks
+:00 Go to dinner at Dish Dash
 == When is it? ==
@@ Line 21: / Line 74: @@
 == Where is it? ==
-Mirantis is playing host in sunny Mountain View, California and will offer lunch and dinner, thank you Mirantis!
+Mirantis is playing host in sunny Mountain View, California and will offer breakfast and lunch, thank you Mirantis! Rackspace is hosting the evening meals, thank you Rackspace!
 Hotels near the Mirantis office:
@@ Line 37: / Line 90: @@
 == What's Expected ==
-What's Expected
+This is free training, but we would like you to get yourself there with these things ready to go.
 Bring a laptop to work on. Mac, Ubuntu, Fedora, and RHEL are known to work. I haven't installed git review on Windows so I don't know if a Windows laptop would work.
-Have the First Time Contributor process finalized, including signing the CLA and getting git review working. The steps are:{{#lst:Documentation/HowTo|first-time-contrib}}
+Have the First Time Contributor process finalized, including signing the CLA and getting git review working. The steps are: [[Documentation/HowTo#First-time_Contributors]]
 You should have current tools installed for working with documentation. This includes Maven and an editor of choice for editing DocBook or WADL documents.
@@ Line 49: / Line 102: @@
 If you don't have a floating license for Oxygen, use Emacs or vi.
-Have git installed, know the basics of git and git review, and have clones of the modules you'll be working on. The main doc repos are:
+Have git installed, know the basics of git and git review, and have clones of the modules you'll be working on locally. Here are the repos we'll be working on:
-openstack/openstack-manuals
-openstack/api-site
+git clone http://github.com/openstack/openstack-manuals.git
+git clone http://github.com/openstack/api-site.git
+git clone http://github.com/openstack-infra/config.git
+A demonstration of some Publican functionality is also planned as part of the activity around build tooling. If you wish to trial the demonstrated steps yourself it is recommended that you come with Publican 3.x installed. Publican 3.x is available in the standard repositories for these Linux distribution releases:
+* Fedora 18 and Fedora 19: https://admin.fedoraproject.org/updates/publican
+* Debian Jessie (testing): http://packages.debian.org/jessie/publican
+* Debian Sid (unstable): http://packages.debian.org/sid/publican
+* Ubuntu Saucy Salamander (Development): https://launchpad.net/ubuntu/+source/publican
+Older releases of these distributions will likely provide Publican 2.8 or lower.
+* Mac OS/X users will need to follow the steps listed at https://fedorahosted.org/publican/wiki/Installing_OSX
+* Windows users can use the EXE installer to install Publican 3.0: http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Users_Guide/chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican-Windows_operating_systems