Documentation Overhaul

[jkillian]

Problem

There are two current sources of documentation: the README and the Github Pages site. The GitHub pages site is out-of-date and visually hard to read. Currently, it should not be used or referenced at all. The README is up-to-date but very long and hard to quickly grok. The current GitHub pages site has the exact same structure and content as the README.

Proposal

Keeping all documentation in the README isn't sustainable or user-friendly. Moving content to the built-in wiki isn't a great idea because the collaborative features are lacking. Instead, let's redo the GitHub pages site and make it the authoritative documentation source. The README will simply contain headings and links to the most important pages in the documentation.

Questions:

• What tooling do we want to use to create/maintain the site? Jekyll? Or something else? Answer: We're using Jekyll, I'm a big fan of its combination of simplicity and features

Fancy Possible Features:

• Generate documentation of rules automatically from metadata contained in each rule (Readout all available rules & options #674). Edit: This is in progress now

[adidahiya]

related: #531

[szahn]

It would be helpful to have an explanation and example of some of the rules and how they affect quality as I'm not sure how too much or too little white space affects code quality. Some of these rules may be more about style and writing error-free code, but a guide outlining the differences between style and quality would be helpful. The following rules were especially confusing to me as I couldn't figure out how important they are to overall quality: align, member-ordering, whitespace.

[myitcv]

Also related, this comment

[jkillian]

Website updated so it's at least readable and reflects the content of the current README. More changes coming in the future

[jkillian]

Reference for a good way to set things up so that you can generate documentation for source code easily onto the gh-pages branch.

[jkillian]

The new documentation site is progressing slowly: http://palantir.github.io/tslint/
It's (very obviously) a WIP, so if anyone is interested in contributing their design or Jekyll skills, let me know!