Jeremy Ashkenas

Side note - it's been a while since i've seen a Docco-style annotated-source-style documentation! http://ashkenas.com/docco/ Backbone.js was the first time i saw it, and I loved it! https://backbonejs.org/docs/backbone.html It demonstrated to me that the libraries I use are just normal code that other people write, and i myself can read it to understand a problem.

I think literate coffeescript might be a better example of popularizing literate programming: http://ashkenas.com/literate-coffeescript/ There also seems to be some traction for literate Haskell: http://www.haskell.org/haskellwiki/Literate_programming I experimented a bit with literate programming on an introductory course in programming using java. It's an interesting experience -- it's very easy to produce a very readable language that is still pretty poor java code, as it becomes so easy to split out fragments and "procedures", rather than follow the more common java class-oriented object orientated way of doing things.

I'm surprised no one has mentioned Literate Programming[1]. It's a concept where comments should reflect the programmer's intentions, explain why, not what is going on, intertwining text and code. It lives on in CoffeeScript and tools like Docco. The just-released Coffeescript 1.6 supports a mix of markdown and code that looks great: http://ashkenas.com/literate-coffeescript/ [1] http://en.wikipedia.org/wiki/Literate_programming

Jeremy Ashkenas (creator of Coffeescript and of docco) is uniquely positioned as an expert in accessible technology. See his hypertext visualization of his thesis project or the various visualizations of government data in his portfolio. He works at DocumentCloud on similar themes. http://ashkenas.com/

I'm pretty excited to see some of the first programs that folks might write with this -- I've got one of my own, a little 400 LOC (half of which is comments) static blogging engine that's currently powering http://ashkenas.com. Part of the idea is that, because first and foremost you're writing a document describing what you're doing, and then filling the the implementation in the gaps ... you end up structuring the program differently than if you started out with the code was at the top level, as usual. For me, it was a fun process -- start with an outline, expand that into paragraphs below, then indent four spaces and implement each paragraph... I'll share the full bit when I make it out of the woods next week, but for now, here's a sneak peek of a rough draft to give a flavor: http://cl.ly/N8Kx Edit: If anyone wants a copy of the hybrid Markdown/CoffeeScript syntax highlighter (for TextMate or Sublime Text), it's available here in the "Syntaxes" folder. https://github.com/jashkenas/coffee-script-tmbundle 10,000 bonus points if you port it over to Pygments and send a pull request to GitHub ;)

I believe that Backbone's annotated source is generated with Docco, another project from the creator of CoffeeScript. https://ashkenas.com/docco/ It's really neat. I wish I published more of my code this way.

The BackboneJS library and the documentation generated by Docco has always been an interesting example. Compare the annotated source with the source at GitHub: https://backbonejs.org/docs/backbone.html https://github.com/jashkenas/backbone/blob/master/backbone.js https://ashkenas.com/docco/

Backbone.js comes to mind: https://backbonejs.org/docs/backbone.html. Edit: The author of backbone.js has a tool that generates documentation in this style. http://ashkenas.com/docco/

I'm intrigued by the concept of literate programming and interested in exploring options for a Scala project I'm working on right now. It looks like this one was done using Docco [1]. Docco supports Scala, and it appears to be a pretty lightweight approach, largely using Markdown. I'm curious whether any literate programming veterans have tooling they prefer? [1] http://ashkenas.com/docco/

It's written with Docco, a tool created by Jeremy Ashkenas. It's used in docs of his other projects, such as CoffeeScript and Backbone, too. http://ashkenas.com/docco/

Also interesting, even if it has become unfashionable these days, Backbone's annotated source: http://backbonejs.org/docs/backbone.html And the tool to make these: http://ashkenas.com/docco/

The only differences from literate coffeescript[0] I see from this demo are that the var keyword is back and print is a macro for console.log. I applaud you for building something cool, but what are the "huge advantages" that you laud in the title? [0] http://ashkenas.com/literate-coffeescript/

if: in_ruby=i=o= gets();taken_care_of_by_a= function_like = puts(i) (from http://web.colby.edu/jasperry/2011/11/10/a-ruby-haiku/) and: Haskell is concise Functional well-typed and neat It is like Haiku (from http://www.haskell.org/haskellwiki/Haiku) and: Journo is coffee's literate publishing app terse prose, wordy code (inspired by http://ashkenas.com/literate-coffeescript/) ...then why is terse programming less expressive and terse literature more expressive?

My guess is it's Docco: http://ashkenas.com/docco/