Objective

The existing crate docs merged in #23413 were minimalistic.

This is not ideal, as there's a ton of complex, interconnected features that are important to explain.
In particular, we want to explain how all of these types, traits and concepts relate to each other
and the broad picture of both "how should you use this crate" and "why does this even exist".

Crate docs are the ideal home for this.

Solution

Write 400 lines of crate docs. Easy.

I am still relatively new to BSN: I haven't had a chance to use it in my projects yet either! Please keep an eye out for both technical and conceptual errors.

Thankfully, the PR description from #23413 was extremely detailed, laying out the architectural context and broader patterns.
The docs on each item, the tests, and to a lesser extent the old design discussions #9538 and #14437 were also very useful.

Notable editorial choices

• relatively high on hype for technical documentation
  • users need to understand why the complexity is useful, ideally without tripping over these problems themselves
  • we really want users to actually use bsn! (and .bsn): the experience is better and standardization is powerful
• intro uses the dreaded "object" word: calling things with multiple entities an "entity" is flatly confusing
  • also very useful for translating the BSN model for users of other engines
• drops users immediately into a Quick Start guide
  • some folks find it extremely useful to see a simple working example before getting the explanation
• explicitly calls out the asset format as future work
  • this is a major, important feature. It's important to acknowledge its absence, and offer workarounds for now.
  • having some information about how it's likely to work allows people to plan effectively.
• I spent a lot of time trying to carefully explain the differences between the composition strategies
  • this mentions asset-format BSN, because it's a primary driver of why we need inheritance
• explaining the FromTemplate / Default distinction was hard but important
• gave an explicit bolded warning about the lack of field overrides
  • I did not call out horrible specialization hack: far too distracting in the crate docs

Important omissions and divergences from past discussions

• GetTemplate was renamed to FromTemplate
• Construct is now Template and FromTemplate
• reactivity (not yet implemented)
• scene composition as a styling/composition alternative (belongs in the bevy_feathers crate docs later)