4 ms·

That time was like 10 years ago. I think it’s been best practice to have docs in the repo for a long time. GitHub Pages came out in 2008.

by prepend 7mo ago

giorgioz 7mo ago
that's true. Take care because in the YCombinator there is "Don't be snarky". Ask yourself how you could have provided the same useful insight without being snarky: https://news.ycombinator.com/newsguidelines.html https://news.ycombinator.com/newsguidelines.html
- satvikpendem 7mo ago
  I don't see anything snarky about their comment. That rule is for cases where people are overly sarcastic and argumentative, not for comments like the above.
  - giorgioz 7mo ago
    snarky critical or mocking in an indirect or sarcastic way. I think the constructive information is mentioning Github Pages were built on .md file and they have existed for 10 years. That's true and useful. The snarky part happens when phrasing the sentence "Ah you guys only doing this now? It has existed for 10 years" that part is talking about something constructive but it's also trying to diminish the discovery of someone else. We all find and develop at different times. In general is better to be constructive and happy someone else is joining you in using something than underline how it was already done in some way by you or others and this new discovery is irrelevant. Everything that exists already existed (in some other shape or smaller parts).
    - prepend 7mo ago
      I disagree. Sometimes it’s useful to point out dumb things. As long as it’s not cruel. I think being efficient in speech is helpful and no need to be constructive with silly or damaging comments. I don’t think this is a case of just finding something late, it’s finding something decades after it’s very common. And strange that the author didn’t reference this old practice.
- prepend 7mo ago
  I don’t think my comment is any snarkier than yours. My intent wasn’t snark, but more incredulity at how the post was written and how it states some very old, commonly accepted best practice was novel or finally time to use. I’d make a similar comment if someone posted that now is the time to use object oriented programming. And I wouldn’t do so in a snarky way.
bryanlarsen 7mo ago
The best time to plant a tree was 30 years ago. The second best time is now.
- rdmuser 7mo ago
  It's a good saying but the literal meaning is not entirely correct anymore. Climate change has changed the math on tree planting in a few ways. For example tree planting in your area today may backfire vs 30 years ago: https://www.scientificamerican.com/article/forest-preservation-tree-planting-could-actually-worsen-climate-change/ https://www.scientificamerican.com/article/forest-preservati...
- 9rx 7mo ago
  The best time to move your docs to your repo was 30 years ago. But now that they are written by LLMs, tomorrow's LLM will be able to write an even better doc than today's LLM. Nothing is gained in caching them now.
  - bryanlarsen 7mo ago
    If that's true, you've got the wrong stuff in your docs. Capture the why's. LLM's can synthesize the what's and how's.
    - 9rx 7mo ago
      Unless you're doing something wrong, the "why" is already captured in your test suite/type system. While you can fairly call that documentation (that is the point of it!), the linked story is about natural language documentation. That can be extracted from your tests/types at will, and as models keep getting better extracting later will be better than extracting now.
      - bryanlarsen 7mo ago
        That's great, if you only want to see the trees. Views of the forest are important too.
mixmastamyk 7mo ago
Python Sphinx as well.
WillAdams 7mo ago
1984 was a bit more than 10 years ago: http://literateprogramming.com/ http://literateprogramming.com/ c.f., https://news.ycombinator.com/item?id=47300747 https://news.ycombinator.com/item?id=47300747
8note 7mo ago
if you aren't using github because you're at a big company with its own git UIs, you still have to make the case that your company needs this thing. I'm sure there's a ton of places where its been hard to do that in the past in a way where the docs are easily accessible where people are looking but with agents, even just pulling the code package to get the docs is fine
- prepend 7mo ago
  I use Jekyll and other builders independent of GitHub. So even weird companies with other git repos can still autogenerate docs.

That time was like 10 years ago. I think it’s been best practice to have docs in the repo for a long time. GitHub Pages came out in 2008.

by prepend 7mo ago

That time was like 10 years ago. I think it’s been best practice to have docs in the repo for a long time. GitHub Pages came out in 2008.

giorgioz 7mo ago

that's true. Take care because in the YCombinator there is "Don't be snarky". Ask yourself how you could have provided the same useful insight without being snarky: https://news.ycombinator.com/newsguidelines.html https://news.ycombinator.com/newsguidelines.html

satvikpendem 7mo ago
I don't see anything snarky about their comment. That rule is for cases where people are overly sarcastic and argumentative, not for comments like the above.
- giorgioz 7mo ago
  snarky critical or mocking in an indirect or sarcastic way. I think the constructive information is mentioning Github Pages were built on .md file and they have existed for 10 years. That's true and useful. The snarky part happens when phrasing the sentence "Ah you guys only doing this now? It has existed for 10 years" that part is talking about something constructive but it's also trying to diminish the discovery of someone else. We all find and develop at different times. In general is better to be constructive and happy someone else is joining you in using something than underline how it was already done in some way by you or others and this new discovery is irrelevant. Everything that exists already existed (in some other shape or smaller parts).
  - prepend 7mo ago
    I disagree. Sometimes it’s useful to point out dumb things. As long as it’s not cruel. I think being efficient in speech is helpful and no need to be constructive with silly or damaging comments. I don’t think this is a case of just finding something late, it’s finding something decades after it’s very common. And strange that the author didn’t reference this old practice.
prepend 7mo ago
I don’t think my comment is any snarkier than yours. My intent wasn’t snark, but more incredulity at how the post was written and how it states some very old, commonly accepted best practice was novel or finally time to use. I’d make a similar comment if someone posted that now is the time to use object oriented programming. And I wouldn’t do so in a snarky way.

bryanlarsen 7mo ago

The best time to plant a tree was 30 years ago. The second best time is now.

rdmuser 7mo ago
It's a good saying but the literal meaning is not entirely correct anymore. Climate change has changed the math on tree planting in a few ways. For example tree planting in your area today may backfire vs 30 years ago: https://www.scientificamerican.com/article/forest-preservation-tree-planting-could-actually-worsen-climate-change/ https://www.scientificamerican.com/article/forest-preservati...
9rx 7mo ago
The best time to move your docs to your repo was 30 years ago. But now that they are written by LLMs, tomorrow's LLM will be able to write an even better doc than today's LLM. Nothing is gained in caching them now.
- bryanlarsen 7mo ago
  If that's true, you've got the wrong stuff in your docs. Capture the why's. LLM's can synthesize the what's and how's.
  - 9rx 7mo ago
    Unless you're doing something wrong, the "why" is already captured in your test suite/type system. While you can fairly call that documentation (that is the point of it!), the linked story is about natural language documentation. That can be extracted from your tests/types at will, and as models keep getting better extracting later will be better than extracting now.
    - bryanlarsen 7mo ago
      That's great, if you only want to see the trees. Views of the forest are important too.

mixmastamyk 7mo ago

Python Sphinx as well.

WillAdams 7mo ago

1984 was a bit more than 10 years ago: http://literateprogramming.com/ http://literateprogramming.com/ c.f., https://news.ycombinator.com/item?id=47300747 https://news.ycombinator.com/item?id=47300747

8note 7mo ago

if you aren't using github because you're at a big company with its own git UIs, you still have to make the case that your company needs this thing. I'm sure there's a ton of places where its been hard to do that in the past in a way where the docs are easily accessible where people are looking but with agents, even just pulling the code package to get the docs is fine

prepend 7mo ago
I use Jekyll and other builders independent of GitHub. So even weird companies with other git repos can still autogenerate docs.