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

61–70 of 87 posts

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

#61

Post by jiggawatts »

theletterf wrote: post #28

There’s an irresistible, almost demoralizing irony in the fact that developers are discovering docs and accessibility only now due to AI. They needed docs and didn’t know it until they had at their disposal an ersatz user in the form of an LLM that asked for context. https://passo.uno/skills-are-docs/

When one of the top Anthropic people said something along the lines of “Our users that invested heavily into their documentation are the best positioned to reap the benefits of AI tooling” I just laughed and laughed, then gazed upon the bare plains of comment-free spaghetti code written by developers who don’t even work here any more.

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

#62

Post by r2vcap »

Interesting idea overall, and I would support doing this if we can.

Some constraints are:

- Non-programmers are not used to working with Git.

- In practice, they (usually PMs or feature designers) need to write their documents somewhere else.

Possible solutions are:

- Make non-programmers use Git as a documentation tool (upgrade your tooling or GTFO).

- Build a two-way sync tool so that programmers and non-programmers can work from the same source.

  - However, in practice, an SSOT (single source of truth) architecture is usually much simpler. Two-way sync tends to be quite difficult, especially across different platforms.

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

#63

Post by [deleted] »

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…

[deleted]

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

#64

Post by cborenstein »

Agree with the post. Working on https://spectagon.md which aims to improve the workflow around reviewing docs in the repo.

Reviewing docs in Github isn't great - as the post mentions, Google Docs or similar is typically where review happens. Spectagon aims to change that so that you can submit PRs for docs and you get a great review experience as a layer on top of Github.

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

#65

Post by jamie_ca »

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…

I see this as not just internal API/architecture/code documentation, but product documentation too. We maintain internal docs about how our product is used for our support, implementation, and sales teams to reference.

Right now it's hosted externally (in our "blessed" knowledge base) but if it could be pulled into the repo, and we set an AI reviewer on every pull request to sanity check that if the changes we're doing have a material impact on the feature as described in those docs that it should be flagged (or changes proposed) that'd be a nice win for keeping them up-to-date, and it's easy enough to publish markdown as html or even script an update to the canonical site when we merge to main.

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

#66

Post by codethief »

seanwilson wrote: post #55
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,…

Agreed. LLM usage just makes the impact more visible.

I bet one of the next "revelations" is going to be: Avoid sprinkling side effects throughout your code. Prefer functional code, push side effects to the boundary (functional core, imperative shell).

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

#68

Post by gitaarik »

jmclnx wrote: post #3

Sounds like they are saying use a repo like git for your documents to help AI read/"understand" your docs. Is that correct ? I am all for using a source control system for your documents, I usually use RCS. But give AI access to your docs, no thanks. If I upload any of my docs to a public server (very rarely happens), they are compressed and encrypted to make sure only I and a few people can view them.

So the code you'll share with an AI, but not the docs?

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

#69

Post by bryanlarsen »

9rx wrote: post #54
bryanlarsen wrote: post #17

Earlier quoted context omitted.

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.

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.

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

#70

Post by starkparker »

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…

As a tech writer, it's not surprising. All LLMs did was get PMs on the same page as TWs, devs, and support toward prioritizing it, because now it benefits feature development in the short term instead of the long term. They can put it on a quarterly review slide and in an OKR, and their bosses will jump up and down and squeal and give them a raise instead of shooting them in the face.
Post reply on HN