search

junkdog / artemis-odb

A continuation of the popular Artemis ECS framework
BSD 2-Clause "Simplified" License
776 stars 111 forks source link

Newbie friendly introduction #312

Closed DaanVanYperen closed 9 years ago

DaanVanYperen commented 9 years ago

@Junkdog said: one way to make the API friendlier for newcomers - maybe mark such methods with a source-only annotation and generate a subset of the javadoc from it? polopoly had @PublicApi, only classes marked with it were included in the javadoc which the client got. We could have a full javadoc and a smaller subset of the javadoc. @NewcomerApior something - most don't need the more advanced features.

fabio-t commented 9 years ago

As a newcomer, let me give my 2 cents. Apologies in advance if not appropriate here.

I personally don't think "restricting" the API would help much. When starting, I go straight to a "functional" documentation (here, the wiki). Wiki entries coupled with functionally complete demos/examples, small in scope but touching all basic features, are a bliss, and what we should aim for. The linked games are good to have, but are often a bit "dodgy" in implementation and hard to follow (ie, using artemis as pros, not as newcomers would).

I for one chose artemis-odb instead of entreri because it had a decent wiki AND I couldn't be bothered to write my own ECS (although I thought about it). It is plausible that I'm not alone in this approach, therefore a cleaner wiki could attract and fidelise several undecided developers.

Also a FAQ with best practices and common pitfalls could be put together. I cannot help yet with that, but you guys must have a good view of what's a good idea doing and what isn't.

DaanVanYperen commented 9 years ago

I feel more for putting efforts in tutorials as well, we've discussed this in this past. Would be a matter of defining some topics. Wiki we can all contribute to.

Also a FAQ with best practices and common pitfalls could be put together.

Probably best in the form of patterns/anti patterns, common solutions and mistakes.

DaanVanYperen commented 9 years ago

moved ticket to contrib.