This document discusses OpenDaylight documentation. It provides an overview of OpenDaylight, an open source SDN project. It describes the OpenDaylight documentation workflow using tools like AsciiDoc, Git and Gerrit. It also explains the process for joining the OpenDaylight documentation community and contributing documentation changes.

1. Essentials of Open Source
Documentation
1

2. What’s in it for 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 an Open Source community
© 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 3

4. Principles of Open Source
• 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 Open Source
• 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 common amongst them?
© 2015 BROCADE COMMUNICATIONS SYSTEMS, INC.
What’s common amongst these?

7. Example of an Open Source project
© 2015 BROCADE COMMUNICATIONS SYSTEMS, INC 7

8. OpenDaylight Architecture for Helium
© 2015 BROCADE COMMUNICATIONS SYSTEMS, INC 8

9. A short video on SDN and OpenDaylight
© 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 9

10. © 2015 BROCADE COMMUNICATIONS SYSTEMS, INC 10

11. Lifecycle of OpenDaylight documentation
© 2015 BROCADE COMMUNICATIONS SYSTEMS, INC. 11
When in doubt, dance it out

12. Key aspects of Open 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 OpenDaylight documentation
• 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 OpenDaylight documentation
© 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 Open Source 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
AsciiDoc is 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 Git and 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 joining Open 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 Source documentation 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 to OpenDaylight 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 website at 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
All images 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.