how to improve our docs?

[cyclotruc]

To improve the contributor experience and make the project more accessible to new users, any ideas to improve documentations are welcome

Current Documentation

The project currently has:

• README.md- Main project overview and basic usage
• CONTRIBUTING.md - Contribution guidelines
• CODE_OF_CONDUCT.md - Community guidelines
• SECURITY.md - Security policy
• llm.txt - text based Instructions for AI agents

Areas for Improvement

1. User documentation:

   • Detailed CLI usage examples
   • Python API documentation with examples

2. Developer documentation:

   • Architecture overview and component relationships
   • Code organization and module responsibilities
   • Development setup and workflow

Let's use this Issue to discuss, do not hesitate to add your ideas

[ix-56h]

An example/ folder with various ways to use the CLI and the package would be great.

On the webapp side, what's the purpose of the /api documentation endpoint ? Since fastapi generate a swagger UI from the pydantic models (and the openapi.json file which's used as reference), i don't see the point of it. Maybe is it planned to describe usages and not for API documentation ?

For the developer documentation, we could have a diagram, maybe powered by gitdiagram and fix the resulting diagram a little. With a bit of hacks, we should be able to keep the diagram up-to-date automatically without that much of human intervention by integrating it in the CI/CD process.

[cyclotruc]

I think example/ is a good idea, especially for AI agents, we can open an Issue for this specific one

About api.jinja it's currently not used nor served, we can scrap it or replace it with an updated version

As for the diagram, I'm unsure yet if tools like gitdiagram are ready for automatic updates of the docs from CI/CD, for now we can instead use it manually to diagrams in Readme files

[ix-56h]

About api.jinja it's currently not used nor served, we can scrap it or replace it with an updated version I have removed the /api endpoint and his related jinja template in my PR #346, i think having the /docs endpoint for the documentation is great enough, after some custom HTML/CSS it's will looks cool af.

As for the diagram, I'm unsure yet if tools like gitdiagram are ready for automatic updates of the docs from CI/CD, for now we can instead use it manually to diagrams in Readme files

Yeah you're right.

[hazrpg]

Saw this in a talk about gitingest, and noticed the /llm.txt when visiting the page, and just thought I'd mention that all the proposals out there suggest using llms.txt and not llm.txt - similar to how AGENTS.md or robots.txt, they are always plural and not singular because they are designed for many things to access them like LLMs, Bots, Agents, etc.

Just thought it was worth mentioning because it might help LLMs find the correct file easier if it uses the same proposed standard that is being suggested.

As some references points:

• Yoast - known for things like SEO in WordPress and general discussions/courses on SEO: https://yoast.com/features/llms-txt/
• LLMs.txt proposal site: https://llmstxt.org/ (and their repo: https://github.com/AnswerDotAI/llms-txt)
• Ahref - another popular SEO site: https://ahrefs.com/blog/what-is-llms-txt/
• Medium - a tech news site, discussing about how tools are starting to include llms.txt: https://medium.com/data-science/llms-txt-414d5121bcb3
• ...and so many more like that.

I thought about pulling the repo to rename the file, but I don't think that's enough of a change to warrant a pull request, but I'm happy to do so though 😅

[ix-56h]

Thanks @hazrpg mentioning this ! And i think you're right.

I'll fix this asap, also, a PR can be open even for small changes like this one !

[github-actions[bot]]

Hi there! We haven’t seen activity here for 45 days, so I’m marking this issue as stale. If you’d like to keep it open, please leave a comment within 10 days. Thanks!

[github-actions[bot]]

Hi there! We haven’t heard anything for 10 days, so I’m closing this issue. Feel free to reopen if you’d like to continue the discussion. Thanks!