After going through the pain of keeping separate repos, branches or even apps for content pages, my team migrated to simply using a CMS.

Wordpress is a bit of a pain, but we found Harmony (http://harmonyapp.com) to be great at serving pages with programmable themes (think haml, sass, etc) that marketing people can still edit without bothering a developer.

Well, the CMS is the classical way to do it. Using Jekyll and Github is a more recent and innovative way to do stuff, much simpler to use for developers and cheaper because it's free hosting that can scale pretty well.

Of course if you want marketing people to edit stuff asking them is use Git is going to be painful.

Install the GitHub app, then tell them to follow these steps: 1) Make your changes. 2) Write a word or two about the changes here (commit subject). 3) Press this button (commit) to record the changes. (repeat 1-3 if desired) 4) Press this button (sync) to sync your changes with your colleagues.

Yea, unfortunately this isn't the best setup for non-technical users, but I think it can still be decently done through the github editing features they recently added. I probably won't use this for some of our more content-heavy sites, but I've grown to appreciate hosting static content on Github pages.

This is for project docs and such, not for marketing people but for the people working on the project.

Nice writeup. The whole "your docs site is just on a different branch" has always been weird to me though. I'm not sure what a better way to do it would be but I don't like these two options: switch branches inline or have a separate clone of the repo.

Yea, but theoretically you could set up a new remote repo just for the site, and use a specific branch for it. I think the convenience is well worth the change in process you have to deal with.

What alternatives to people recommend?

Not the same thing (since this isn't an API), but I like what balanced does: https://github.com/balanced/balanced-api

I'm using a Jenkins build to run Sphinx on my Python projects. Having to move the changes into the gh-pages branch is a bit awkward, but it's working pretty well.