WIP: Rewrite documentation #63
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Geppetto implements the Controller tier using the Command Pattern. Commands are automatically instantiated and executed in response to Application Events. | ||
|
|
||
| ### Context | ||
| Metaphorically speaking, if different modules of your app could be considered separate *living entities*, the `Geppetto.Context` would be like each being's *central nervous system*. The Context is responsible for facilitating communication and sharing data between components *within a given module*, providing encapsulation so that this sharing does not extend past the boundaries of that module. This communication is achieved through the standard [Backbone.Events](http://backbonejs.org/#Events) module, with some syntactic sugar for allowing intercontextual communication. |
There was a problem hiding this comment.
Brilliant description - I really struggled to find the right metaphor for the Context. This is perfect!
|
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! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 😀
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!