Hacker News new | past | comments | ask | show | jobs | submit login

I agree that having a "Show code" button only at the end prevents disrupting the reading flow.

In terms of "code with explanation" layout, I really like todos.js' approach: http://backbonejs.org/docs/todos.html

It also works with images: http://www.ifixit.com/Teardown/Mac+Pro+Late+2013+Teardown/20...

Most layouts nowadays fail to take advantage of the horizontal space available. It's just 2 colums in the end, but it goes a long way.




The todos.js one was generated by a tool called Docco, created by Jeremy Ashkenas (creator of Backbone, Underscore, and CoffeeScript). I agree that it looks really good and more people should use it for their projects!

http://jashkenas.github.io/docco/


>created by Jeremy Ashkenas (creator of Backbone, Underscore, and CoffeeScript)

Just out of curiosity, why did you include that? Do people make judgements about tools based on the person who wrote it?


Actually I was originally going to add "so that is why you will see it frequently on projects related to those technologies," just to give some background and link it all together (e.g. the cited example is hosted on the backbone site).

But yeah, it also gives it some star power and instant credibility, and I wanted to highlight jashkenas for his significant contributions. (As a side note I don't currently use any of them, I prefer Angular and vanilla JS syntax.)


I'd say yes. If you took the time to independently evaluate every tool that was ever produced, you wouldn't have time for anything else. So instead, people rely on crude, biased, but effective heuristics, the author's past achievements being one of them.

It's the same thing with novel authors - I'm much more likely to purchase a book by Stephen King than an unknown author's debut album if that's all I know about the books.


In my experience, unknown authors do tend to make terrible debut albums :)


I just tested out a new tutorial layout on my blog that utilized two columns.. It still has the code in the main column, but the examples get pushed to the side..

http://wegnerdesign.com/blog/learning-svg-with-logos/


Ooh that's really pretty.

I was going to bring up the IPython notebook functionality, in part because it was used as a follow-up to another xkcd strip ("Regex Golf", http://nbviewer.ipython.org/url/norvig.com/ipython/xkcd1313.... ), but I gotta say that one looks nicer :) The use-cases are slightly different, though.


Jasmine did this too! http://pivotal.github.io/jasmine/

... todos.js' did it better though.


ifixit's layouts are actually a product of: http://www.dozuki.com/




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: