Ditch Your CMS – Git + Markdown + Static Sites Generators

View Github Repository Open presentation in a new window

patrickarlt

See all presentation from patrickarlt

Ditch Your CMS – Git + Markdown + Static Sites Generators

1 1

ditch-your-cms-talk

Replace your CMS and start generating documentation with Git and static site generators

On Github patrickarlt / ditch-your-cms-talk

Ditch Your CMS

Git + Markdown + Static Sites Generators

Twitter : @patrickarlt / Slides : http://bit.ly/1fW17GQ

Who Am I?

  • Experience Developer
  • Esri PDX R&D Center, previously Geoloqi
  • I love building products for developers
  • Started working on ArcGIS for Developers

ArcGIS for Developers

Do something great for our developer community, reach new markets, and promote our platform.

Started small, few pages about features, then added developer tooling, and finally…

MVP

Documentation

What we had…

  • Thousands of pages of doc
  • Dozens of products
  • All in an old CMS
  • No one liked using the CMS
other wikis, teams built their own custom tools, the CMS process was inhibiting our ability to write doc

What we wanted…

We wanted people to develop documentation like we developed the developers site.

Not just writing documentation, building documentation.

How could we apply our existing tooling to writing documentation?

github (history of git at esri), static site generators

Static Site Generator

Static Site Generators

  • Treat documents like source code.
  • Tools to build large amounts of pages quickly.
  • Like a CMS where all the files are your computer.

Lots Of Choices

  • Ruby (Middleman, Jeykll)
  • JavaScript (Wintersmith, DocPad)
  • PHP (Droplets, Stacy)
  • Python (Pelican, Hyde)

Static sites take care of the hard parts of building a website and writers to focus on content.

Markdown

What Is Markdown?

Markdown is a formatting language that outputs as HTML.

# Header

This will be a paragraph with some *italic* and **bold** text, a [link](http://example.com) and an image ![label](http://placekitten.com/200/200).

<h1>HTML is fine too</h1>

Extensibility

Markdown is easy to extend to almost any use case.

  • Table of contents
  • Formatting helpers
  • Pairs well w/ static site generators

Git / GitHub

What Is Git?

Used by developers to manage source code.

  • Versioning and rollback
  • Development workflow
  • Release management
  • Collaboration

What Is GitHub?

Extra collaboration tools on top of Git…

  • Issues
  • Wikis
  • Pull Requests

Demo Time

Why?

Control

We have absolute control over how content is organized and presented.

Flexibility

We use these same system to build developer tools and marketing pages.

Extensibity

These tools are designed to be extensible to fit use cases.

Ownership

Teams have been eager to learn these tools and have more ownership over their content.

Collaboration

Allows anyone on any team to look at and edit documentation.

But…

But do all my writers/proofreaders/editors have to learn all this?

Your development team can help you learn these tools. Learning curve isn't much higher then a CMS.

But what about all the stuff in our CMS?

Servers like (Nginx and Apache) make it easy to serve static files alongside a CMS.

But everyone has to preview the site locally?

Automate the build process and automatically build and deploy the site when you push changes to GitHub.

Where We Are Going…

  • More automation
  • More custom tools
  • More training

In The End

  • Bring developers and documentarians closer togather
  • Documentarians start thinking like developers
  • Encourages collaboration and communication
still using cms, but more teams are working with us to build custom systems and train them in managing docs w/ our tools.

Thanks!

Twitter : @patrickarlt / Slides : http://bit.ly/1fW17GQ