6 ms·

Code documentation written as code

76 points by logvol 13y ago

martin-adams 13y ago
I do like it but not sure how well it would work when you need to express code that is over multiple files.
spindritf 13y ago
This is a really great format which lends itself to a whole range of mid-to-low level computer tasks. Programming/scripting, obviously, but now there's a tools section which I'm guessing will also catch on. You could describe ip(6)tables like that, or ssh.
Nilzor 13y ago
Exactly what am I looking at here? I think if you want attention to your HN-posts you should put a bit more effort into it than simply linking to a git repo.
- pwg 13y ago
  One of github's UI flubs, in my opinion, is that the main repo page puts the code file name listing at the top, and the "README" at the bottom, so with any substantial repository, one has to scroll down "below-the-fold" before one gets to the description part of the page. A reasonable (somewhat) interface for contributors. A very lacking UI for promoting the value of the code base to non-contributors.
  - spellboots 13y ago
    Or you can just append #readme: https://github.com/adambard/learnxinyminutes-docs#readme https://github.com/adambard/learnxinyminutes-docs#readme
- coldtea 13y ago
  I thought hackers were supposed to be curious and not giving up after the smallest possible annoyance.
  - clebio 13y ago
    Context is nice to have, though.
  - npsimons 13y ago
    "Attention is scarce. Information is not. Do the math." - Nina Paley Just because something makes it to the frontpage of HN doesn't automatically make it worthy of further investigation. Granted, one shouldn't just fling things aside because they have no immediately apparent utility, but just from the difference in the submitted headline and the first line of the linked to page, this smells a bit of coder-drama.
- justncase80 13y ago
  Agreed. I looked at it for a while but don't get it. It just looks like a bunch of code snippets to examples of languages. Not super valuable.
gcr 13y ago
What is OP talking about? People like Djikstra have been advocating this since the 1970s.
- jaredmcateer 13y ago
  This isnt so much code documentation as it is simple examples of usage for a given language.
logvol 13y ago
I didn't realize that there is a website for this: http://learnxinyminutes.com http://learnxinyminutes.com Also didn't realize that the site had been posted before. :S

76 points by logvol 13y ago

I do like it but not sure how well it would work when you need to express code that is over multiple files.

This is a really great format which lends itself to a whole range of mid-to-low level computer tasks. Programming/scripting, obviously, but now there's a tools section which I'm guessing will also catch on. You could describe ip(6)tables like that, or ssh.

Nilzor 13y ago

Exactly what am I looking at here? I think if you want attention to your HN-posts you should put a bit more effort into it than simply linking to a git repo.

pwg 13y ago
One of github's UI flubs, in my opinion, is that the main repo page puts the code file name listing at the top, and the "README" at the bottom, so with any substantial repository, one has to scroll down "below-the-fold" before one gets to the description part of the page. A reasonable (somewhat) interface for contributors. A very lacking UI for promoting the value of the code base to non-contributors.
- spellboots 13y ago
  Or you can just append #readme: https://github.com/adambard/learnxinyminutes-docs#readme https://github.com/adambard/learnxinyminutes-docs#readme
coldtea 13y ago
I thought hackers were supposed to be curious and not giving up after the smallest possible annoyance.
- clebio 13y ago
  Context is nice to have, though.
- npsimons 13y ago
  "Attention is scarce. Information is not. Do the math." - Nina Paley Just because something makes it to the frontpage of HN doesn't automatically make it worthy of further investigation. Granted, one shouldn't just fling things aside because they have no immediately apparent utility, but just from the difference in the submitted headline and the first line of the linked to page, this smells a bit of coder-drama.
justncase80 13y ago
Agreed. I looked at it for a while but don't get it. It just looks like a bunch of code snippets to examples of languages. Not super valuable.

gcr 13y ago

What is OP talking about? People like Djikstra have been advocating this since the 1970s.

jaredmcateer 13y ago
This isnt so much code documentation as it is simple examples of usage for a given language.

logvol 13y ago

I didn't realize that there is a website for this: http://learnxinyminutes.com http://learnxinyminutes.com Also didn't realize that the site had been posted before. :S