Essentials of Open Source Documentation

Essentials of Open Source Documentation

• 1.
  Essentials of OpenSource Documentation 1
• 2.
  What’s in itfor me? • Glimpse of an Open Source community • Example of an Open Source project • Lifecycle of OpenDaylight documentation • Tools of Open Source documentation • Process of joining the OpenDaylight community © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC.
• 3.
  Glimpse of anOpen Source community © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 3
• 4.
  Principles of OpenSource • Open Exchange of the source code • Free remix and redistribution • Rapid prototyping • Meritocracy • End to vendor lock-in • Community for a higher degree of cooperation © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC 4
• 5.
  Myths of OpenSource • Open = No control on the work • Open= Unsafe • Open Source = 100% Open Source • Open Source = Crowd Sourced • Open Source = Not enterprise grade © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 5
• 6.
  What is commonamongst them? © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. What’s common amongst these?
• 7.
  Example of anOpen Source project © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC 7
• 8.
  OpenDaylight Architecture forHelium © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC 8
• 9.
  A short videoon SDN and OpenDaylight © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 9
• 10.
  © 2015 BROCADECOMMUNICATIONS SYSTEMS, INC 10
• 11.
  Lifecycle of OpenDaylightdocumentation © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 11 When in doubt, dance it out
• 12.
  Key aspects ofOpen Source documentation • Document infrastructure and tooling—Moving away from the status quo • Working with user generated content—Making developer jargon palatable • Collaboration in a flat hierarchy—Shared accountability amongst all • Organic processes—Adapt processes continuously to changing requirements © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC 12 65% of developers from over 150 Fortune 500 companies cited documentation as one of the biggest challenges of Open Source software -- Your Life as a Developer Survey 2013
• 13.
  Goals of OpenDaylightdocumentation • Build the content infrastructure. • Improve the user content for OpenDaylight projects. • Ensure continued content quality. • Manage the authoring and publishing process. • Set documentation methods and policies. © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 13
• 14.
  Challenges of OpenDaylightdocumentation © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 14 • Project scope ‒ On-the-fly project creation ‒ More than 42 projects • Timelines ‒ Six months cycle per release ‒ Fast-paced requirements • People ‒ Few writers ‒ Volunteering != permanence ‒ Creating code is fun, not reviewing documents
• 15.
  Tools of OpenSource documentation © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 15
• 16.
  OpenDaylight documentation workflow ©2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 16 Project build manager website Documentation repository
• 17.
  Overview of AsciiDoc AsciiDocis a text document format for writing notes, documentation, articles, books, eBooks, slideshows, web pages, man pages, and blogs. © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 17
• 18.
  Overview of Gitand Gerrit © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC 18 Git is an Open Source distributed version control system. Git allows a team of people to work together, all using the same files. The creation, merging, and deletion of the individual branches is seamless and fast. Gerrit is a free, web-based software code review tool and is used to review documentation.
• 19.
  Process of joiningOpen Daylight documentation © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 19
• 20.
  OpenDaylight documentation process 1.Create a Gerrit account. 2. Clone the documentation repository by using Git. 3. Create a branch to your local machine. 4. Navigate to the respective folder for the manual by using Git. 5. Use ASCIIDOC to make text changes. 6. Check in your branch to the repository and merge the changes. 7. Use the maven install command to compile the documentation. © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC 20
• 21.
  Why Open Sourcedocumentation is the Bees’ Knees? • Access to cutting edge networking technology • Work with some of the greatest minds in the SDN world • Learn new tools • Work in a collaborative environment • Tackle new challenges • Expand your networking circle © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 21
• 22.
  Your ticket toOpenDaylight documentation 1. Download the controller or see a demo of the product at: https://www.youtube.com/watch?v=g_Gp30kGdec&index=8&li st=PL8F5jrwEpGAhSUlVz14S50aSRfHCWLXOQ. 2. Review the documentation at: wiki.opendaylight.org. 3. Connect with the documentation group in their weekly meetings. 4. Join the conversation through lists.opendaylight.org and ask.opendaylight.org. 5. Set up your documentation tools at: https://wiki.opendaylight.org/view/CrossProject:Documentation _Group:Tools 6. Volunteer for your first documentation task in the documentation@lists.opendaylight.org. © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 22
• 23.
  Thank you
• 24.
  References • OpenDaylight websiteat http://opendaylight.org/ • YouTube video on Open Source at https://www.youtube.com/watch?v=a8fHgx9mE5U • The Open Source way at http://www.theopensourceway.org/ • Network World, Myths of Open Source at http://www.networkworld.com/article/2603133/opensource-subnet/debunking-the-top- open-source-myths.html • Wikipedia, Software-defined networking at http://en.wikipedia.org/wiki/Software- defined_networking • Gerrit at https://code.google.com/p/gerrit/ • Git at http://git-scm.com/ • AsciiDoc at http://www.methods.co.nz/asciidoc/ © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC.
• 25.
  Note on Images Allimages are taken from the internet. We were unable to locate the rightful owners and copyright infringement is not intended. If you are the owner of any of these images, you may contact us at any of the following email addresses: ‒ mborah@Brocade.com ‒ sthiruva@Brocade.com ‒ dshetty@Brocade.com © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC.