Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

It's time to move your docs in the repo

dein.fr

Post reply on HN
Print view View original

81–87 of 87 posts

Re: It's time to move your docs in the repo

#81

Post by kingstnap »

lelanthran wrote: post #77
ronsor wrote: post #38

Earlier quoted context omitted.

AI means that you cannot defer software design until you've written half code; you cannot defer documentation to random notes at the end. It has the effect of finally forcing people to think about the software they're making, assuming they care about quality. If they didn't, then it's not practically different from an insecure low-code app or something copy-pasted from 15 year old StackOverflow answers.

> AI means that you cannot defer software design until you've written half code; you cannot defer documentation to random notes at the end. > It has the effect of finally forcing people to think about the software they're making, Ah, and all this time I was reliably assured that waterfall, design-upfront, was a broken process...

Single iteration waterfall is a broken process. You really need those late stage usage feedback signals unless your requirements were somehow captured by God.

Re: It's time to move your docs in the repo

#82

Post by prepend »

bryanlarsen wrote: post #17
prepend wrote: post #4

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.

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

Isn’t the second best time 29 years and 364 days?

I get the principle but it seems like there are many other times to plant than now.

Re: It's time to move your docs in the repo

#83

Post by prepend »

8note wrote: post #60
prepend wrote: post #4

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.

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

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

Re: It's time to move your docs in the repo

#84

Post by prepend »

giorgioz wrote: post #12
prepend wrote: post #4

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.

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

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.

Re: It's time to move your docs in the repo

#85

Post by prepend »

giorgioz wrote: post #73
satvikpendem wrote: post #15

Earlier quoted context omitted.

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.

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…

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.

Re: It's time to move your docs in the repo

#86

Post by thangalin »

moritz wrote: post #51
thangalin wrote: post #11

Earlier quoted context omitted.

> difficult to keep [...] docs updated with actual code I used my software and R Markdown documents to help address such problems. In the source code, you have: // DOC SNIPPET BEGAN: example_api_usage /** */ function amazing_function( char life, long universe, string everything ) { } // DOC SNIPPET ENDED In the R Markdown you write an R function to parse all snippets, then refer to snippets by name. If the snippet ca…

In the Elixir ecosystem (where documentation is considered a "first-class citizen" in the language), you can run code examples as part of your test suite in a similar fashion ("doctest"): https://elixir-recipes.github.io/testing/doctests/

> documentation is considered a "first-class citizen"

How exquisitely Knuthian!

Re: It's time to move your docs in the repo

#87

Post by lelanthran »

kingstnap wrote: post #81
lelanthran wrote: post #77

Earlier quoted context omitted.

> AI means that you cannot defer software design until you've written half code; you cannot defer documentation to random notes at the end. > It has the effect of finally forcing people to think about the software they're making, Ah, and all this time I was reliably assured that waterfall, design-upfront, was a broken process...

Single iteration waterfall is a broken process. You really need those late stage usage feedback signals unless your requirements were somehow captured by God.

> Single iteration waterfall is a broken process. You really need those late stage usage feedback signals unless your requirements were somehow captured by God.

Waterfall, as prescribed and as practiced, had feedback signals.

Post reply on HN