Bevy docs improvement

[CorneliusCornbread]

Hey all, I wanted to start this discussion out with saying how incredibly helpful and well written Bevy's news articles are. Which is exactly what I wanted to talk about. I'm unsure about other developers but I find the change logs provided by the news articles for each new version are incredibly helpful for documentation.

Let me give an example, the recently added EntityRef is an incredibly important (imho) and powerful tool provided by Bevy. And the news article for 0.15 gives a wonderful explanation on what it is, how to use it, and why it's a useful addition. All things which are incredibly helpful when figuring out how a developer would want to tackle a problem in this game engine. Yet comparatively, its documentation is incredibly barren.

Now I know immediately the response to this is going to be "Bevy is not in 1.0, API breakages are common," and I agree completely, but if we spent all this time writing these amazing news articles, do you think we could link to them, or at the very least make these articles searchable? At the moment this isn't a huge issue, but when bevy is on, say, 0.64, this issue is going to get very difficult to work around. So I propose a few possible solutions:

• Improve the search engine index-ability of these articles
  • I'm not a super experienced web dev, but I believe Bevy could include tags about the article's content for search engines. For example 0.15's update article could include a 'EntityRef' or a 'run_system_cached' tag, something such that if someone searches the API they can find the related articles.
• Add a search to the bevy website directly
  • Whilst this has quite a bit of upfront work, it would be a one time cost, and would also, similarly, help make these news articles index-able.
• Link to articles which show the changes of the API in the docs
  • This one is much harder, but would functionally serve the same purpose. I'm putting this one last as it has the largest impact on the development cycle for the folks who maintain this project

I would be partial to the first most option, as it would be the most intuitive likely how to most developers search for information about API, especially since the bevy cheat book exists. It would require going in and creating these tags for the whole article, but it would likely be much less work than the other two.

[alice-i-cecile]

Generally I view release note articles as ephemeral, and targeted primarily at communicating changes and marketing the engine. The correct solution IMO is to port valuable content from the release notes (and migration guides) into the docs themselves. If you see these problems; please open issues for them!

In terms of process, I think that the in-repo release notes have started to make a very large impact: encouraging us to spread out this high-quality writing work across the cycle, and giving reviewers to point out "hey while you're at it can you add that to our docs?".

I would be interested in moving more of our writing process into the monorepo to encourage that further, but that's a decision with non trivial tradeoffs around CI, contributor friction and artifacts in the git repository that would need to be resolved.

[CorneliusCornbread]

Generally I view release note articles as ephemeral, and targeted primarily at communicating changes and marketing the engine. The correct solution IMO is to port valuable content from the release notes (and migration guides) into the docs themselves. If you see these problems; please open issues for them!

In terms of process, I think that the in-repo release notes have started to make a very large impact: encouraging us to spread out this high-quality writing work across the cycle, and giving reviewers to point out "hey while you're at it can you add that to our docs?".

I would be interested in moving more of our writing process into the monorepo to encourage that further, but that's a decision with non trivial tradeoffs around CI, contributor friction and artifacts in the git repository that would need to be resolved.

The only reason I didn't specifically focus on this was because it seemed like the obvious answer, and assumed it hadn't been done because the development capacity wasn't really there, especially considering how fast this project moves.

Equally, if the better approach is to start skimming through release articles to improve the docs I think that is also a great solution, however, it does introduce the burden that future changes will have to change the documentation accordingly. I assumed that's why the docs have been kept quite simple, as incorrect docs can also be incredibly frustrating.

[alice-i-cecile]

This is mostly a process issue, rather than capacity. Over time this will become increasingly important, and thankfully this work can be very comfortably delegated.

I assumed that's why the docs have been kept quite simple, as incorrect docs can also be incredibly frustrating

Indeed, this was historically true :) Over time, the standards for documentation have crept up though, and we've done a good job at maintaining it even through breaking changes (as long as its co-located and easy to find during changes and review).