Get On Gittin’ On! Using Git repositories for content Paul Zimmerman Manager, DevNet Operations, Cisco Systems March 7, 2016 Hi everyone, I’m Paul Zimmerman from Cisco, and I’m going to talk with you about my experience with Git and related distributed repositories for content management.

My Journey Managed doc team in large group: DITA/XML Moved to managing developer docs Worked on OpenDaylight Started working with distributed toolchain Questions: How to collaborate with developers? How to build professional-looking docs outside of the XML toolchain? Do we use DITA? So, I was a doc manager like so many of you… using a DITA-based XML publishing system. Most Cisco products are documented using a system built of Astoria and XMetaL (moving to Oxygen). However, a couple of years ago, I moved over to a developer docs position, and I had to learn a whole new world of distributed repositories. I was managing the docs for one of Cisco’s early forays into software defined networking, and we needed to be more aligned with the developers in producing content. At first, we worked with what we knew best… we created the docs in XML. However, as we started to work on open source projects like Open Daylight, we had to learn new skills. I met Colin Dixon, a fellow from the Linux Foundation, who had this great toolchain that he built for OpenStack, where authors could create in Markdown, post to Git, and the build would be automated. Sounded great!

What is Git? Ok, so the first thing I had to do was figure out what this distributed repo model was all about.

git Git Defined GIT - the stupid content tracker "git" can mean anything, depending on your mood. random three-letter combination that is pronounceable, and not actually used by any common UNIX command. The fact that it is a mispronunciation of "get" may or may not be relevant. stupid. contemptible and despicable. simple. Take your pick from the dictionary of slang. "global information tracker": you're in a good mood, and it actually works for you. Angels sing, and a light suddenly fills the room. "goddamn idiotic truckload of sh*t": when it breaks git noun \ˈgIt\ 1. an unpleasant or contemptible person. (British slang) a widely used source code management system for software development. What is Git? When we first started using Git, one of my colleagues was British and thought that this was a terrible name for a tool! Obviously, we are not talked about stupid or contemptible people, but instead a source code management system. Linus Torvalds said "I'm an egotistical bastard, and I name all my projects after myself. First 'Linux', now 'git'.” Here’s the definition from the Git source code readme file

Flavors of Git Git – Version control tool Ways to host Git for collaboration: GitHub GitLab Bitbucket Stash CloudForge … and many more! The problem with Git is that it’s so ancient that we have to use the command line—or Terminal if you’re a Mac user—in order to access it, typing in snippets of code like ‘90s hackers. This can be a difficult proposition for modern computer users. That’s where GitHub comes in. GitHub makes Git easier to use in two ways. First, if you download the GitHub software to your computer, it provides a visual interface to help you manage your version-controlled projects locally. Second, creating an account on GitHub.com brings your version-controlled projects to the Web, and ties in social network features for good measure.

Remote (online) repository Git Basics Remote (online) repository Local repository Master branch Project branch Fork/Branch Commit Pull request To publishing automation Distributed version control system Have entire repo on your system Source – branch – fork – pull – push

Git vs. CCMS Git CCMS Free/open source Proprietary and expensive Small team support Can support large teams No automated localization Translation and localization support Simple conditions: In or not Complex conditions Simple & easy authoring XML/DITA structured authoring (not so easy for non-writers) Content lives in unique repo Content can be shared across docs Check out entire repo, pull/merge Single file checkout

Using Git as a Content Repo

Why? Make writing easier Allow developers build the experiences Spend less time on how to write and more on how to build

Collaboration on Content Same workflows as code development Same rewards as developers (gamification) Distributed system allows many contributors SMEs and contributors can review content Reviewers can fix docs

Cross-Platform Works on Linux, Windows, Macs Authoring can be done in Markdown or other simple language Also allows XML if desired (DocBook, others)

Git Publishing Toolchains End-to-end toolchain Provides source control for code and content Provides automation for reviews, publishing Can be done with open-source tools

Continuous Integration and Delivery Continuous Integration (CI): code/content continually tested, integrated with other changes, merged. Continuous deployment (CD): changes continuously deployed with each patch Content is continuously tested, merged with each patch and published. CI implies that the code is continually tested, integrated with other code changes, and then merged. Continuous deployment (CD) means the code is continously deployed with each patch to the entire code base. In the case of documentation, it means the content is continuously tested, merged with each patch and published. OpenStack has multiple projects merging multiple changes every day, so the documentation system also needs to be able to keep up with that many changes. Writers have the same workflow that developers use, and get the same recognition and rewards as developer contributors. It takes the burden of building documentation off of local writer's environments, although contributors still need to be able to build docs locally. By having a built draft ready for review, casual contributors and reviewers avoid the overhead of downloading the patch, replicating the build environment, and then building the docs. We can review both the source and output thanks to the automation in the system. The speed of the builds increases because writers can work on multiple patches at once while the cloud-based CI/CD continues to run.

Customizable Toolchain Built of components Code/content review (Gerrit) Continuous integration (Jenkins) Static site generators https://staticsitegenerators.net/ Doc sets can be built through the toolchain

Use in Open Source Docs: OpenStack OpenStack has multiple projects merging multiple changes every day System needs to keep up with that many changes Speed of the builds increases because writers can work on multiple patches at once while the cloud-based CI/CD continues to run. First and foremost, Git is used to manage open-source code development. It made a lot of sense to use Git for the content that goes along with the code. Content is stored in repos, accessible by the development team Documentation is a key part of the deliverables Variety of implementations based on motivations of team Markdown files are shown in Git itself These files can be built into doc sets

Use in Corporate Documentation Teams Relatively easy to set up Cheap, open source components Customizable Training and example code Collaborative Lots of examples: https://github.com/PharkMillups/beautiful-docs Typically, corporate documentation teams have a more robust content management system. However, as more developer products are developed, writers can leverage code reviews and such by aligning the content with the code.

Use Along with Developer Products For many developer products, content is just readme Found in Git itself and many developer repos Code samples, etc For the team I work with, the developer code is the product. In this case, we are actually sending developers to our Git repos for the product. In this case, we definitely want the end user to use Git. This is probably the simplest implementation, as the docs can live with the code.

Git and DITA

Why Integrate Git and DITA? Small team wants DITA content management Pull developer content into doc set

DITA Content Management for Small Teams In a small team, a Git repo can be leveraged for a DITA CMS Need a CI tool like Jenkins for builds XML editor XML-aware database for link management http://www.dita-for-small-teams.org/

Pulling Developer Content into DITA Pulling Markdown into XML was a one-way trip Can do research and collaboration in Markdown, move to DITA for topic single-sourcing and publishing Automation makes this feasible DITA Open Toolkit plug-in: https://github.com/jelovirt/dita-ot- markdown

…But Round-Tripping is Possible Restructured Text (rST) to DITA conversion available Takes some management and communication Allows writers and developers to work together https://github.com/mgcalo/rst2dita

Cisco DevNet and Git

Git for Sample Code Straight Markdown attached to sample code snippets Very basic implementation https://github.com/CiscoDevNet

Repo for Learning Labs Collaboration with developers Toolchain for publishing Can update quickly https://learninglabs.cisco.com/

Automated Toolchain for DevNet Docs “Editors” manage the structure “Authors” can contribute directly to repo Editors manage commits/merges Most authors do not have to install toolchain OK, publishing to Git or using it as a repo for content is one thing, but the real prize is the automated toolchain.

Not Done Yet! Working on more features Round-trip with Cisco XML solution Increasing flexibility Better integration with code http://developer.cisco.com

References

For more information… http://git-scm.com/book/en/v2 https://github.com/PharkMillups/beautiful-docs http://docs.writethedocs.org/ http://readwrite.com/2013/09/30/understanding-github-a-journey-for- beginners-part-1 http://drmacros-xml-rants.blogspot.com/2014/01/dita-without-cms- tools-for-small-teams.html http://www.dita-for-small-teams.org/ https://github.com/mgcalo/rst2dita http://infotexture.net/2015/04/dita-ot-markdown-plugin/