More importantly move your docs from anything else to pure markdown. Finally we are free from weird file formats and superfluous syntax for docs.
[flagged]
It's time to move your docs in the repo
21–30 of 87 posts
Re: It's time to move your docs in the repo
#22That 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.
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-preservati...
Re: It's time to move your docs in the repo
#23Bit of a plug I suppose, but this was what motivated me to set up AS Notes, my VS code extension which makes VS Code a personal knowledge management system, with linking and markdown tooling. I've built an html converter so they can be published to github pages from the repo. It's here if it's of interest to anyone https://www.appsoftware.com/blog/as-notes-turn-vs-code-into-... ... I'm so much more motivated to write docs when a) its easy to keep them up to date using an agent, and b) someone (agents) will actually read them!
Re: It's time to move your docs in the repo
#24We 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 a…
Sentry MCP is great, “find out top 10 issues by users affected, check what it would take to fix and if you think it’s a low risk fix, apply it. Open a PR that links to the issues and explain the issue and the fix in three sentences max”.
Re: It's time to move your docs in the repo
#25It 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 years now, whether it was for software I wrote for myself, for my tiny open source projects or for businesses. I will obviously continue to do so and it has nothing to do with:
> AI changes the game
The reason is simply that tests and documentation are useful to humans working on the codebase. They help people understand the system and maintain it over time. If these practices also benefit LLMs then that is certainly a bonus, but these practices were valuable long before LLMs existed and they remain valuable even now regardless of how AI may have changed the game.
It is also a bit funny that these considerations did not seem very common when the beneficiaries were fellow human collaborators, but are now being portrayed as very important once LLMs are involved. I'd argue that fellow humans and your future self deserved these considerations even more in the first place. Still, if LLMs are what finally motivate people to write good documentation and good tests, I suppose that is a good outcome since humans will end up benefiting from it too.
Re: It's time to move your docs in the repo
#26That 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.
Python Sphinx as well.
Re: It's time to move your docs in the repo
#27It 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…
Well, it's timely because there's a docs platform that has surged in popularity, and it really is not a good idea for most of those who need technical docs to be using a SaaS that approximates Squarespace.
Re: It's time to move your docs in the repo
#28There’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.
Re: It's time to move your docs in the repo
#29When I start a new project with a team I start off with asking 'how we will work' and part of that is 'how we will communicate'. Less is more in that world. Jira, confluence, github, slack, email, standup, ad-hock meetings, bongo drums, etc etc. The more places you communicate the harder it is to keep everyone on the same page. I have always been a fan of putting docs next to code for this exact reason and, as far as I can tell, it has been the right decisions every time.
With AI code assistants I personally spend 90% of time/tokens on design and understanding and that means creating docs that represent the feature and the changes needed to implement it so I can really see the value growing over time to this approach. Software engineering is evolving to be less about writing the code and more about designing the system and this is supporting that trend.
In the end I don't think AI hasn't fundamentally changed the benefit/detractor equation, it is just emphasizing that docs are part of the code and making it more obvious that putting them in the code is generally pretty beneficial.
Re: It's time to move your docs in the repo
#30There’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/
Strongly agreed. However, some developers have trouble writing clearly and reading lots of text, and therefore prefer oral and interactive + real-time transmission of the information. Those developers, I suppose and hope, are discovering that they can talk out loud to their agents, explain everything interactively, and then the agent can create whatever longer-term artifact it wants to record the understanding. Multi-modal interfaces FTW?