Write the Docs: Patrick Arlt – Ditch your CMS with Git and Static Site Generators

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Patrick started the afternoon talks after the amazing snack break. He posted his slides ahead of his talk, smart idea. Patrick works at Esri and previously worked at Geoloqi. There he fell in love with making products for developers. When Geoloqi was acquired by Esri he started working on the ArcGIS site for developers.

This site aims to do something great for Esri’s developer community. They try to reach new markets and promote the broader platform. The first version of the site was a single, simple page. It took a few weeks to get up to 6 or 7 pages. Over time they added more and more information to help bring people on board.

Eventually they realized there wasn’t really documentation on the site. It was a lot of external links and pointers. What they had was thousands of pages of doc for dozens of projects with all of it sitting in an old CMS that no one liked. Entire teams had built their own CMS just so they didn’t have to use the painful CMS. This wasn’t what they wanted.

What they wanted was a way to develop documentation like they develop their own product. They wanted to shift to not just writing documentation but building documentation. That led them to look at their existing toolkit and see what could be applied to documentation.

The first thing they had was a static site generator. This let them treat documents like source code. There are tools to build large amounts of pages quickly. It’s like a CMS but all the files sit on your local computer. Needless to say there are tons of choices. Static sites take care of the hard parts of building a website so writers can focus on writing content.

Within this site generator they use Markdown for content. It’s a very simple language that, under the hood, gives them a lot of advantages for writing documentation.

The last tool they really rely upon is the git / GitHub combination. They use it to manage all of their source code so it was a natural extension to use it for documentation content. The GitHub portion is used for tracking issues. They use the issues feature in GitHub to track bugs in documentation just as you would with a code project.

These tools mean that teams have a lot more ownership over their documentation. Anyone who is a part of the organization can contribute to documentation using the same tools they contribute to the product with.

To those concerns about the learning curve with all these Patrick suggests placing it in the context of bring new people up to speed with a complicated CMS system. In each case you’re needing to train people and maintain internal documentation on best practices.

But what about all that documentation in their old CMS? Well, they’re still using it. Patrick sees that as an okay combination. They’re able to serve the static files alongside the old CMS content.

Esri is next looking at 3 main things:

  • More automation. Things like making previewing site changes more easily.
  • More custom tools.
  • More training.