Core concepts guide

[jamesplease]

Guides are short explanations of features of Marionette, written by the maintainers of the library. We can use Guides to answer high-level questions, like "What is a CompositeView for?" and "When might I use Radio?" They're also a good place for us to provide beginners with basic information that can help them get started.

@benmccormick suggested we write a "Core Concepts" page that introduces the most fundamental ideas of Marionette in a way that beginners could grasp. It isn't intended to be extensive, nor all that detailed. It's just a high-level look at the things people are most likely to encounter when writing their first Marionette app.

I wrote a first draft that you can read by clicking the link below.

Read the draft here

I intentionally left a few things out.

View Classes

We should not get into the different view types here, I think. This page should be readable in a few minutes, and if we start parsing out the differences between the views, then we would be both introducing a lot of concepts and writing a lot of text. Neither of those things are consistent with the broad goals of this document.

Radio

I would consider Radio to be an 'advanced' feature of Marionette, by which I mean that it is most useful when writing more complex apps. Simpler apps might not need it at all! As such, it has been omitted.

Object

I would group this in with Radio as a more advanced feature.

Modules

We should not be putting any emphasis on these things anymore, I think.

Behavior

This is too specific to the View class, I think. Introducing this in a Guide dedicated to explaining the ins and outs of Views, and only Views, is a more appropriate place for these.

Region Manager

This is an object that I hope we can deprecate. We should actively promote never using these directly, and instead starting your view tree with – you guessed it – a view.

TemplateCache/Renderer

Like Behaviors, these are too specific to Views for the purpose of this doc, I think.

[samccone]

Do you think a UML esk diagram would be helpful for this? I kinda do

[benmccormick]

@jmeas I forked your gist with some grammar stuff and a few small additions here: https://gist.github.com/benmccormick/60e089402da1b72773dd

@samccone I think some sort of diagram might help, maybe a prettied up version of something like this for explaining Views? http://benmccormick.org/content/images/2014/12/renderpattern-3.png

Also I'd vote for Radio as a core concept, but I'll defer to you guys there

[jamesplease]

Do you think a UML esk diagram would be helpful for this? I kinda do

Diagrams will definitely be helpful throughout the guides, but I'm not sure if now is the right time to introduce them. This page is to be a high-level explanation that just gets the gist of things across, and I'm not sure if a single diagram could accomplish that.

I think that any diagram that we include would either be too specific, like the one @benmccormick posted above, or too complex to fit in with the rest of the content (which, again, is intended to be digestible introductory material).

If we end up having lots of diagrams, then that's also a problem, I think. At that point we would be getting too far into the specifics of how things work.

I agree that the example shown in @benmccormick's diagram is a good candidate for a basic diagram that could potentially be on this page, but I have concerns with it.

First, it focuses too much on one of the view types. All four are different. Why show the ItemView? Because it's the most common, maybe? Why show an ItemView that is backed by a model? Why not one that's backed by a collection? There are all of these different ways to use ItemViews that no single diagram will explain. And if we just include one diagram, then people may incorrectly assume that the one configuration presented is the idiomatic way to use that particular Class.

When it comes to diagrams, I think we should hold off until we're really explaining a particular pattern, which, yes, will happen in the guides, but maybe not in this 3-minute introduction to Marionette's concepts.

[benmccormick]

Yeah @jmeas I think you're right. Not the right fit for this page.