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

11–20 of 87 posts

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

#11

Post by thangalin »

petcat wrote: post #5

Out-of-band docs have always been a constant source of frustration and discrepancies. It's really difficult to keep readme.com docs updated with actual code releases because there's no hard constraint preventing one from updating without the other. It just relies on "convention".

> 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 can't be found, building the documentation fails, and noisily breaks a CI/CD pipeline.

What's nice is that you can then use this to parse C++ definitions into Markdown tables to render nicely formatted content.

The general idea is that you can have "living" documentation reference source code and break on mismatch. Whether you use knitr/pandoc or python or KeenWrite/R Markdown[1] is an implementation detail.

[1]: https://keenwrite.com/

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

#12

Post by giorgioz »

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

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

#13

Post by giorgioz »

dheera wrote: post #8
themanmaran wrote: post #6

We just did this the other week and it's such a great setup using AI. Monorepos in general are better for coding agents since it's a single location to search. But now we have the ability to say "Add xyz optional param to our API" and claude adds the code + updates the documentation. I was also able to quickly ask "look at our API and our docs, find anything out of date". Our set up is: packages/ ↳ server ↳ app ↳ doc…

The one thing I hate about monorepos is nothing ever gets versioned, packaged, and shipped. Polyrepos are workable, the way to do it is to actually version, ship, and document every subcomponent. When I mean ship, I really mean ship, as in a .deb package or python wheel with a version number, not a commit hash. AI can work with this as well, as long as it has access to the docs (which can also be AI-generated).

The monorepo make it easier to ship the overall product but harder to ship parts of it. I've used a monorepo for the past 13 years and I got all shared packages with version 0.0.0 and I still haven't figured out a simple way to share just some parts of it like a CLI. Does anyone have a monorepo and publishes NPM packages with source code of only that folder? Sub-gits required to pull in multiple places...

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

#14

Post by twelve40 »

alansaber wrote: post #10

Not sure I agree with this. MD files need to be constantly synced to code state- why not just grep the code files? This is just more unstructured indexing

yeah my teammates seem to enjoy checking in endless walls of MD texts of "documentation" generated by llms after it's done adding a feature. So even if that's an extreme and your documentation is more thoughtful, there is still a problem of:

* redundancy with the code: if code samples can be generated from the code, why bother duplicating them? what do they add? can they not be llm-generated later? and possibly kept somewhere out of the way (like, a website) so as not to clutter the codebase with redundancy

* if you do go for this duplication, then you are on the hook for ensuring it's always up-to-date otherwise it becomes worse than duplicate: misleading

So my preference is, when adding something to the repo, think very hard whether this information is redundant or not. Handcrafted docs, notes, comments that add more context like why was this built that way after a ton of deliberation - yes. Anything that is trivially derived from the code itself - no.

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

#15

Post by satvikpendem »

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 see anything snarky about their comment. That rule is for cases where people are overly sarcastic and argumentative, not for comments like the above.

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

#16

Post by giorgioz »

themanmaran wrote: post #6

We just did this the other week and it's such a great setup using AI. Monorepos in general are better for coding agents since it's a single location to search. But now we have the ability to say "Add xyz optional param to our API" and claude adds the code + updates the documentation. I was also able to quickly ask "look at our API and our docs, find anything out of date". Our set up is: packages/ ↳ server ↳ app ↳ doc…

Yes it's awesome! I'm creating a lot of CLIs with Claude Code to interact with external services. Yesterday made a CLI for the Google Search Console so I can prompt "get all problems from indexing in Google Search Console and fix them". Same with Sentry bugs. Same with the customer support "Use the the customer support cli skill to get recent conversations from customers and rank bug reporting and features requests and suggest things to work on"

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

#19

Post by MoreQARespect »

twelve40 wrote: post #14
alansaber wrote: post #10

Not sure I agree with this. MD files need to be constantly synced to code state- why not just grep the code files? This is just more unstructured indexing

yeah my teammates seem to enjoy checking in endless walls of MD texts of "documentation" generated by llms after it's done adding a feature. So even if that's an extreme and your documentation is more thoughtful, there is still a problem of: * redundancy with the code: if code samples can be generated from the code, why bother duplicating them? what do they add? can they not be llm-generated later? and possibly kept…

I've been trying to push people to use hitchstory or similar to generate docs from specification tests precisely to avoid that redundancy but most people just look blankly at it and go "why don't you just do that with AI?"

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

#20

Post by redgridtactical »

The biggest win for me with docs-in-repo isn't the AI angle, it's that pull requests can't land without updating the relevant docs. When your support pages, privacy policy, and README all live in the same repo, they naturally stay in sync with the code.

GitHub Pages serving directly from a /docs folder makes it even simpler, no separate deploy, no separate CMS, no drift. The less infrastructure between writing and publishing, the more likely docs actually get maintained.

Post reply on HN