When @tomdale and I started iterating on Guides materials, we made the decision to make guides focused and succinct rather than in-depth explorations of their topics.
Occasionally we get contributions that address particular concerns or confusion that individual readers have with the guides. The tradeoff in accepting these contributions is we slowly drift away from our original goal of succinctness.
No single commit, of course, does this. There is the concern that over time these commits will decrease guide clarity and, since we arrive at the point haphazardly, not be especially good in-depth guides either.
So, moving forward, what should we do? Some options:
Recognize that we cannot remove 100% confusion for 100% of people, keep the guides focused, and leave non-essential information to blogs, books, and SO questions.
Abandon the short guide approach and consciously enact a plan to become in-depth guides like Rails Guides.
Keep the short guides and add companion More Information Than You Require guides.
Split each guide page into two sections: basic and extended.
I think that the short hard-hitting guides are quite important, and our focus should probably stay as is.
I do think there is room for non-essential extended information to exist somewhere on the main website. The question is where?
This is my favorite option (of those listed). It allows the detailed nitty-gritty discussion that some of us geek out over while not forcing it in the face of each and every reader of the guides.
To me the main issue with this is that then each guide has two purposes. To give an intro and to give the fullest detail possible for a subject. I personally think these two things are at odds with on another.
I really like the way Apple writes itâs guides and documentation. They offer both a succinct overview of certain classes, like the current API reference in Ember, but also have extensive programming guides that explain the rationale and common use cases.
That for example the UITableView. The class reference offers short information on each of the methods, but also gives a short overview of the class, requirements, etc. The Table View Programming Guide gives extensive information, including a closer look, examples of common use cases and problems, rationale etc.
I really like this separation since I can quickly get to what I need. Quick info: class reference, in depth info: programming guide.
Self contained âchaptersâ
I also believe âchaptersâ should be as much self contained as needed. You shouldnât need to read a guide from beginning beginning to end in order to understand it. It should be possible to jump to a chapter and absorb it solely. What I mean is that I think itâs better to not reference examples from previous chapters etc.
I also think better guide outlines would help. For example, in the routing guide there is a pretty vital part of information called âinitial routesâ. Right now it requires you to read through the whole guide it order to find it. Most users would just stumble upon this, you canât really search for it.
Howerver, if it was a separate entry in the sidebar, it would be much more accessible imho.
I authored the contribution mentioned above. Assuming that the ultimate goal of the guides is to increase Ember.js adoption, I think the guides should (also) address the audience segment consisting of people who are still deciding whether Ember is right for them or not, and who might base this decision on their ability to use Ember in an existing codebase. (at work?)
Iâm not sure what the right way of doing that is. Separate âEmber for existing codebasesâ section? Something other than a guide?
The main concerns that I would have are browser compatibility (existing codebases usually imply an existing commitment to supporting some browsers), and whether Ember conflicts with other libraries. (e.g., prototype modifications) Ember seems to have well thought-out solutions to these issues, so it would be nice to have a place that gets these questions out of the way and tells the audience segment I mentioned above that it is OK to spend their time learning Ember.
+1 This would be awesome. The Rails Guides and the way they are organised are a great intro and consistent go-to resource for all the major aspects of the framework.
2.) Organize cookbooks and guides to follow unified code examples when possible. Useful to see common project example cover the different aspects of the framework. If people contribute to the guides they should attempt to do so in a way that provides context to a well documented reference application or two.
3.) More guides on esoteric concepts (maybe beginner and advanced). Perhaps a guide on the run loop, and some of the underlying architecture.
4.) Curated list of code examples. I think this is what the cookbooks are about. Probably could stand to have guides reference cookbook segments when more detail is required.
5.) A guide that compares and contrasts Ember to other popular frameworks (Angular, Backbone, Knockout, etc.)
I personally like when guides explain the why of something and not just the how. I really like the âUnderstanding Ember.jsâ section of the guide. More of that.
Well first let me say that I think you guys are doing a fantastic job overall with the entire project in general, kudos. It is difficult to try to figure out what information to focus on because what is a beginner or advanced topic will vary between each person. So I can see where the statement ârealize that you can not clear up 100% of confusionâ is valid. Now, I am by no means an expert in Ember and I hope that my insight is of some help. I can really only speak on my experience so far with learning Ember.
The guides and the Todo.app guides are great and I think the intentions of the guides are in the right place but from learning Ember I am realizing that it is deceiving complex so brushing over topics will be challenging. A solution like you said might be to have another âcompanionâ section that dives into topics more in depth. I am currently using multiple resources to try to fill in the gaps that I had from reading through the guides but searching through the internet to find the right information is tough and much of the information is outdated.
I think the guides should some how incorporate an overall picture of how Ember works and how an App would function within or in conjunction with Ember either maybe a video or diagram. Cause knowing the overall architecture or a high level birds eye view of something goes a long way while learning. I watched a video from either Tom or Yehuda that explained it pretty darn good and I had an âOooohhhhhhâ moment.
I also had a hard time finding the possible âhooksâ in like a Route for example maybe just a list would be great. Lastly I would say more code snippets of the elements within the API section might be useful. You have some and others have none. I was reading that someone else was working on a cookbook type section with code examples that may be a good solution for now.
The other minor things are mostly how some things are writing within the guides, I would suggest to prepare it as if no one knows what the heck you are speaking about. Overall I would say if you are going to breeze over topics at least give a link to get further information some where online. Well I hope I gave some useful feedback maybe all the things that I am talking about is some where and I just did not see it. If I could help with something I surely would.
I think either one of the above would be fine. I love the first because Iâm pretty sure it has a lot to do with Rails adoption an growth but I also see the advantage in the second.
I kind of like the TL;DR approach taken in ember blog posts lately.
I think every guide should have a dual structure.
Start with the âexecutive summaryâ short and sweet.
But repeat with much more in-depth detail, theory and exposition and perhaps even snippets of relevant source code. The exposition and opinion is really helpful because it provides a mindset and frame of reference that becomes invaluable by the time you start to read the API docs.
Perhaps guides start their life as a short and brief skeleton, and just the gist. This gets us more guides to work with. More topic coverage quickly.
And as demand and feedback dictate a more in depth variant evolves and shadows each guide. With the short version cross linking to the in-depth version.
This obviously creates more work for the documentation contributors. But Trek has done a great job raising the documentation bar significantly which is great for the project long term I think.
Also, I am very +1 +1 +1 what @ecryan said. Assume nothing of the reader. When topics are breezed over provide links to resources for further research. This rings true with my experience. When I first started reading it feel very magical and confusing. But it is only by being obsessive and then going back and rereading the guides that things really started to click for me.
I think links into the API or else surgically jumping into the source code can be really convenient. I am willing to bet what many people consider the âhurdleâ and cognitive load to learning Ember is that they are not yet intimately familiar with how everything is organized. And so a lot of energy is spent finding stuff.
The web site will be how many people first experience Ember, and gently leading (or rather pushing) them into the actual source code of the framework is not necessarily a bad thing, IMHO.
Also, @trek donât worry you will get to take weekends off when Ember hits 2.0 But only one weekend, because there will be more work to do!
Although reading the source code could be helpful, think it should never be needed to read the source in order to understand the framework. Pushing or leading users to the source code smells to me like: âYeah, we could write a nice documentation, but hey, just look at this code and youâll probably figure it outâ.
I just had the biggest âduhâ moment I just realized why⌠LolâŚThanks wycats. You schooled me without saying a word⌠Lol⌠Thanks for the link bro.
But only one weekend, because there will be more work to do!