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

51–60 of 87 posts

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

#51

Post by moritz »

thangalin wrote: post #11
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 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/

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

#52

Post by formerly_proven »

susam wrote: post #25

It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices. 'You must write docs. Docs must be in your repo. You must write tests. You must document your architecture. Etc. Etc.' These were all best practices before LLMs existed and they remain so even now. I have been writing extensive documentation for all my software for something like twenty year…

There's a pattern where people create AI-specific infrastructure for coding agents which is essentially instantly obsolete because it's pointless. Stuff like most MCPs (instead of just using a CLI), agent-specific files (CLAUDE.md, AGENTS.MD, github-instructions.NET etc.) etc.

> You should have a good, concise introduction to the codebase that allows anyone to write and test a simple patch in under 15 minutes.

Yeah, that's the CONTRIBUTING file.

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

#53

Post by philipp-gayret »

sigbottle wrote: post #32

There's a lot of things that we mean when we say 'docs'. The great talk "No Vibes Allowed" put me to the far end of the other extreme - persistent long term state on disk is bad . Always force agents to rebuild, aggressively sub agent or use tools to compress context. The code should be self documenting as much as possible and structured in a way such that it's easy to grep through it. No inline docs trying to descri…

One of the better ways to maintain docs I've seen is with tests that let you describe what the inputs and outputs were for an API, and from it the framework generated your docs. (This was Spring Rest Docs) We included aggressive checks to have every input and output tested, it meant we had one truth about what fields existed: The code was aligned with the tests, and the tests were also the docs. I really liked this idea; Just one record of the truth. Granted it doesn't capture the intent of the code perfectly, but it solves a lot of the garbage collection.

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

#54

Post by 9rx »

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.

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.

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

#55

Post by seanwilson »

susam wrote: post #25

It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices. 'You must write docs. Docs must be in your repo. You must write tests. You must document your architecture. Etc. Etc.' These were all best practices before LLMs existed and they remain so even now. I have been writing extensive documentation for all my software for something like twenty year…

> It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices.

Maybe it's the speed of LLM iteration that makes the benefit more immediately obvious, vs seeing it unfold with a team of people over a longer time? It's almost like running a study?

I have a similar reaction to strong static types being advocated to help LLMs understanding/debugging code, catching bugs, refactoring... when it's obvious to me this helps humans as well.

Curious how "this practice helps LLMs be more productive" relates to studies that try to show this with human programmers, where running convincing human studies is really difficult. Besides problems with context sizes, are there best practices that help LLMs a lot but not humans?

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

#56

Post by nulltrace »

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

Grepping works when you wrote the code. Not so much when someone else installs your package and has no idea which export is public API. We added a one-page markdown saying "use these, ignore the rest" and the wrong-import issues mostly stopped.

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

#57

Post by ErroneousBosh »

susam wrote: post #25

It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices. 'You must write docs. Docs must be in your repo. You must write tests. You must document your architecture. Etc. Etc.' These were all best practices before LLMs existed and they remain so even now. I have been writing extensive documentation for all my software for something like twenty year…

> These were all best practices before LLMs existed and they remain so even now

Okay, so what, should I be moving my docs out of the repo or something?

How should I make it as hard as possible for LLMs to make any use of or suggestions about my documentation?

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

#58

Post by 8note »

susam wrote: post #25

It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices. 'You must write docs. Docs must be in your repo. You must write tests. You must document your architecture. Etc. Etc.' These were all best practices before LLMs existed and they remain so even now. I have been writing extensive documentation for all my software for something like twenty year…

there's an implicit ownership change, from having technical writers own the documentation, to including it as part of the commit.

when things are tiny or resource constrained, the same people are doing each task regardless, but "technical writer" is a real job around documentation and manual writing, so there's at least sometimes some real decoupling between the code and outwards facing documents.

that also covers for cases where people can write code well, but who's english(or whatever the target documentation language is) is shaky at best.

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

#59

Post by 8note »

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…

couldnt the docs be a build output rather than a dedicated folder? keep the docs close to the code they document?

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

#60

Post by 8note »

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

Post reply on HN