geekdave
commented
10 years ago No offense taken at all. This is desperately needed, especially since the docs were not overhauled when we introduced DI (which is obviously a major conceptual change).
The English looks great so far - please keep it coming!
Hey @geekdave, I hope you don't mind or feel insulted, but I wasn't entirely satisfied with the documentation. I don't know, I think it feels like it was assembled in bits and pieces. Which it obviously was :grinning:
Especially for newcomers (w/o a RL background) I think it must be pretty confusing and hard to understand why to use Geppetto in the first place. So I started to rewrite the full README.
It's WIP, I paused at the triple horizontal rule, just to have a clear visual distinction of how far I got.
So, what I've done and where it's heading at: I decided to cut most of the details out and just show how the pieces fit together with an easy example and only the most essential of explanations. My purpose is to split out the full documentation on the various pieces into separate files. This has a double benefit IMO: if you're new to Geppetto you're not overwhelmed with exceptions, syntactic sugar which muddles the basics. On the other hand if you're a seasoned Geppetto user and need to look something up it will be easier to do so if there's a clear demarcation in files. Oh and we desperately need a full API description.
Anyway, as you probably guessed English isn't my native tongue, so there's bound to be a horrific number of grammatical errors and misconstrued sentences.
Let me know what you think, and if you don't like it at all, no problem!