Say you have a web application with signed up end-users, or business clients with a subset of their employees as users. You’re going to want to have a help system. You could bake that into the web-application itself, serving the content over HTTP co-mingled with dynamic pages and static artifacts (.png, .css, .js etc). If you do you’re really limiting the ability of help editors to react to news, and update help, as they are tied to the release schedule of the app itself. That is, unless your help pages leverage a CMS. Here is LinkedIn’s help:

It is on a separate sub-domain. It is actually an instance of RightNow Technologies’ Web Experience, so they went the CMS route.

Cheapest

We could do this more cheaply. GitHub’s ‘pages’ (gh-pages) system is a worthy hosting platform for something like a help system. You get to edit page source in markdown (or other simple text format), and with gh-pages built-in templating and site-decoration capability, the end product can be nicely polished. After the initial setup, the people who edit content can be non-technical. GitHub-pages provides a nice web interface for simple editing of existing pages. Like linkedin, developers can map the resulting help to a domain name. Developers will need to learn gh-pages’ underlying technologies - Jekyll and Liquid, but after the initial setup can forget them.

Editing for Non-techies

That’s best completely discussed here on GitHub’s own blog.

Cheap Enough

You may want to protect your help source. Especially if it is for a version of the site that’s not published yet. GitHub provides a $7/mo version of their service that allows people to have a private source, yet still use the gh-pages system to publish to a public site. The way the github people intend you to manage change that’s not yet published to ‘live’ help pages, is via branches. The trouble is that you can’t see that branch in rendered form. For that you’ll need to manage say your ‘staging’ and ‘live’ versions of help on GitHub ‘forks’. The trouble with that and the $7/mo account is that you can’t have a fork of the same repository within the same account. You’d have to have a second $7/mo account to have your private fork in. Seems unnecessary to me, but the GitHub folks tell me that there are technical reasons why one account can’t have two forks of the same repository. By the way I previously thought I had a loop-hole, fork the repo to another account, but then transfer ownership back again after renaming it. That’s now blocked:

I hope they overcome that restriction or issue.

Nice Side Effects

When we use a SCM as the backing store, we get some nice side effects. Specifically we can merge sets of changes simply. All that preparation work for a release against the ‘staging’ help set, can be merged atomically to the ‘live’ branch/fork, With branch within one repo, it’s a developer activity. With the fork approach, its possible to complete the merge via GitHub’s web interface - meaning the non-technical help editor could do it.

Another nice side effect it the ability to model divergence on specific items. What that means that ‘live’ and ‘staging’ could differ on a couple of specific items. That could be as simple as the site title atop each page. The developers would perform the merges in such a way that the divergence was maintained for subsequent merges of ‘all’. This though would be better for situations where multiple live sites represent help for different clients. For example a custom “linkedin” instance for IBM, and another for Accenture need not share a help system.

Making it more interactive

With the likes of Knockout or Angular, a rudimentary search system can easily be built into an otherwise static app. What does that look like? Go here and type in the search field (top left). None of that involves a server side interaction It is easy for gh-pages to make the meta-data necessary for that search to work.

To recap

• GitHub-pages is the hosting (yay Git!).
• Jekyll and Angular and Knockout are the technologies.
• Non-technical users edit in the incredibly simple markdown syntax.
• Those users can workflow changes to pertinent environments themselves.
• Developers can do heavy lifting by using GitHub to its fullest extent.
• Merging between environments is possible and easy.
• The solution is $0 or $7/mo depending on your point of view.

Markdown for newbies

Oh, and for those that don’t know, here’s Markdown’s source format for the section above:

Syndicated

Aug 6, 2012: This article was syndicated by DZone