1. 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.

2. 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!

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

4. 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

5. 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.

6. 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

7. 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

8. Using Git as a Content Repo

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

10. 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

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

12. 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

13. 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.

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

15. 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

16. Use in Corporate Documentation Teams
Relatively easy to set up
Cheap, open source components
Customizable
Training and example code
Collaborative
Lots of examples:
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.

17. 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.

18. Git and DITA

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

20. 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

21. 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: markdown

22. …But Round-Tripping is Possible
Restructured Text (rST) to DITA conversion available
Takes some management and communication
Allows writers and developers to work together

23. Cisco DevNet and Git

24. Git for Sample Code Straight Markdown attached to sample code snippets
Very basic implementation

25. Repo for Learning Labs Collaboration with developers
Toolchain for publishing
Can update quickly

26. 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.

27. Not Done Yet! Working on more features
Round-trip with Cisco XML solution
Increasing flexibility
Better integration with code

28. References

29. For more information… http://git-scm.com/book/en/v2
beginners-part-1
tools-for-small-teams.html