chaplinjs/chaplin — pull request #569 by knuton (2013-05-04 17:50:34+00:00)
Title: A proposal for hosted docs

This is a proposal on how to give the documentation for Chaplin some more glory, while still keeping them close to the source for convenient maintenance. It also builds on @paulmillr's work to have bi-lingual (CoffeeScript/JavaScript) docs.

It would be nice to have some more freedom in the presentation of the docs, make browsing them more convenient, and offer an option to switch between the two languages to reduce visual noise.

At the same time, as @molily told me, an earlier attempt at keeping the docs in a separate repo has been abandoned due to trouble with keeping source and documentation in sync.

My basic idea for remedying both is to leave documentation source files where they are now, but use GitHub Pages to make them available to the public. Using [Jekyll](https://github.com/mojombo/jekyll), the existing files can be transformed into a more easy-to-use, more browsable collection of docs, without having to change too much.

You can see my first steps into this direction here: http://knuton.github.io/chaplin/chaplin.collection_view.html

I have slightly adapted the styles from chaplinjs.org and added the option to choose one's preferred language at the top of the page (persisted in localStorage).

The individual doc files would not have to change much in order to accomodate this change: https://github.com/chaplinjs/chaplin/commit/06ea47f50310fb5a11c8a29670ec2537c863b969#L4R0

Another addition I would like to make is to add a sidebar or some other option to jump between modules quickly.

The main benefits I expect from this are
* the option to choose a preferred language,
* ease of navigation, more discoverability,
* stability of docs for current release (if docs are deployed to docs.chaplin.org on every release).

I'd like to hear your feedback. Paul has already expressed his concerns in an inline note. Paul, can you explain how this suggestion would be harder to maintain compared with the current setup?