search

bevyengine / bevy

A refreshingly simple data-driven game engine built in Rust
https://bevyengine.org
Apache License 2.0
36.11k stars 3.56k forks source link

Fill Out Documentation and Improve Usability #143

Closed TheArchitect4855 closed 3 years ago

TheArchitect4855 commented 4 years ago

The documentation is sparse, and in my opinion it should be a pretty high priority. Especially with new users coming in, thorough documentation is very important.

I would love to help contribute and fill out the documentation myself, but I'll need help in knowing what certain functions do and how they should ideally be used.

Thoughts? Is it too soon for filling out the docs because APIs will be changing all the time, or is this really something that should be addressed?

zicklag commented 4 years ago

Like was mentioned in the announcement post here.

Bevy's APIs are still very unstable, so I haven't spent much time documenting anything yet. The Bevy Book is still small and the Rust API Docs have plenty of gaps. In general I subscribe to the idea of "documentation proportional to stability". As features stabilize and design patterns emerge, we will increase efforts in both of those areas.

Being that everything is so unstable as of yet, I would say it is probably too early to spend a lot of time on documentation, though I completely agree with the importance of the documentation.

My initial thought is that if you wanted to go through and start adding some descriptions to stuff it wouldn't hurt, just realize that it could change and the documentation might have to be removed ( or you could updated it ) if it becomes inaccurate. I think we don't want to spend a lot of "development time" on interfaces that are extremely unstable yet, but if you ore somebody else wants to run through and add descriptions as they are able that doesn't hurt.

TheArchitect4855 commented 4 years ago

That's more or less what I was thinking - I'd just need help from the people more familiar with the engine to vet my docs or help me make them.

GabCampbell commented 4 years ago

Hey I think you should consider changer the title to something that sounds more actionable. Something like: "Add x", "Increase X in Y", "Fix X", "Change X".

alice-i-cecile commented 3 years ago

Absolutely agree, but I'm going to close this in favor of more actionable specific issues.