Revamping document structure

[akshaydeo]

Hey folks, we've heard your feedback loud and clear about our docs, and we're rolling up our sleeves to fix things up so onboarding is smooth sailing. Your opinions matter, so hit us with your thoughts and suggestions. We'll keep dropping updates here about how we're rethinking the docs' hierarchy and making things easier to find.

[sammcj]

Love the initiative! Here's my feedback:

Readme spread

Having the documentation spread out across different directories throughout the codebase makes it hard to work with.

If you don't know what you're looking for - you have to hunt through the codebase and read through multiple READMEs to figure out which one has the information that applies to you.

Example:

Duplicated information

A number of the READMEs seem to have duplicated information such as contributing and links to quick start etc.

Example: https://github.com/maximhq/bifrost/blob/main/ui/README.md#-contributing

Less is more, focus on config & examples

Each readme places quite an emphasis on features. While this is probably OK to have somewhere, with it spread throughout all the readme files it has the effect of bloating the documentation.

I've had a similar issue with documentation written by Claude and coding agents in general. Recently I've taken to prompting them with something along the lines of "When writing documentation, keep the focus technical. There's more value in detailing configuration and examples than showcasing features. When writing content ask yourself 'What is the value that this is adding?'."

Example:

ref

Misc

• If documentation needs to sprawl Search becomes critical, I like that it's available on your new documentation website.
• It's nice to have all configuration options / environment variables in one location.
• It's not clear in the current documentation the cost of model requests are discovered, where they can be configured and if they take prompt cache hits/writes/misses into account.