Rethink the documentation design and implementation

[balupton]

These examples are nice:

• http://skeljs.org/docs

Ideas:

• Medium.com style comments in a second column

Good guidelines for great documentation:

• http://jacobian.org/writing/great-documentation/
• http://stevelosh.com/blog/2013/09/teach-dont-tell/

[greduan]

skelJS does have nice docs but wouldn't they be a tad bit difficult to implement? Also what would the content structure of the .md files of the documentation be? Perhaps it would be better to go with a .textile documentation for this since it allows much more control over the file's structure?

[greduan]

I just found something similar to what I said about having the code on the right side and the documentation on the left: http://raynes.github.io/lein-newnew/

[chase]

@greduan, that uses a Lisp-equivalent of Docco, which is arguably worse than JavaDocs for explaining how code works.

[greduan]

Oh I didn't mean actually use that. But rather I think it showed the idea quite well; code on the right and all the explanation and documentation on the left.

[balupton]

@SteveMcArthur did a lot of work on this over at https://github.com/docpad/website/tree/redesign

[balupton]

none of the original links work, so closing