search

Renanse / Ardor3D

Ardor3D is a free Java based, professionally oriented, open source 3D graphics engine.
Other
229 stars 77 forks source link

Needs better documentation #89

Open Igrium opened 5 years ago

Igrium commented 5 years ago

I'm not sure where to comment this, so I'm doing this as an issue. You NEED better documentation.

Right now your only form of tutorial is something telling you how to copy paste from your example code, and even then, I can't figure out the context it should be running in because you abstracted out your initialization code. You have an outline for in introduction tutorial, but I can't find the tutorial itself. Right now, the only way to figure out how to use this thing is to reverse engineer your example code, which is not good.

If you want people to use your API, you need to fix this.

Igrium commented 5 years ago

Edit: Reading back, I realize I sound a little harsh. Sorry. I'm just a little frustrated that it's taken me a long time to even get the example working. I'm sure this is a great API.

Renanse commented 5 years ago

Sorry, it DOES need better docs. Things got a little stale when I took a leave of absence from working on the project and we lost the forums and such. Probably the easiest way to get up and running is probably to build from scratch with Eclipse and gradle. From there, extending ExampleBase is a quick way to get something of your own up for testing.

Igrium commented 5 years ago

Okay, thanks. I'm leaving this issue open because you seem to be using the issues as a todo list.

jfelrod1960 commented 5 years ago

@Renanse have you thought about the format for the documentation? For example, a PDF document or Wiki pages. Is there an outline to start with or one planned? I could help from time to time. :)

Renanse commented 5 years ago

I have not really. A lot has changed in the 11 years we've been around, so might be worth looking around to at current best practices.

On Thu, Sep 19, 2019 at 1:01 PM Jeffrey Elrod notifications@github.com wrote:

@Renanse https://github.com/Renanse have you thought about the format for the documentation? For example, a PDF document or Wiki pages. Is there an outline to start with or one planned? I could help from time to time. :)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/Renanse/Ardor3D/issues/89?email_source=notifications&email_token=AAOXBW4RM7ETLO3BKKVLYITQKO465A5CNFSM4IXI45BKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7EKK4I#issuecomment-533243249, or mute the thread https://github.com/notifications/unsubscribe-auth/AAOXBWYFNRHUEJ5Q7T5ATVTQKO465ANCNFSM4IXI45BA .