New MDG project: The Meteor Guide

[arunoda]

@sashko I made some comments about the performance monitoring chapter. (or lessons)
What do you think?

Include some of the tools from Kadira

I can work on these.

[mitar]

Great stuff.

A random comment. Maybe it would be useful for you to read relevant chapters from the following two books:

• http://producingoss.com/en/
• http://open-advice.org/

As it seems you are trying to organize open source community there are some amazing resources available, experiences and insights. I am not sure if you have consulted such and similar resources, so I am sharing them here. I found them interesting to read, things often look obvious afterwards, but sometimes there are good ideas to prepare in advance.

[sashko]

Thanks for posting! I’ll check those out ASAP.

[massimosgrelli]

Great news! It’s something really necessary. I need to get a better understanding of how to make things right the first time in a Meteor app. During these months I went through massive refactoring of my project’s modules more than once. In many cases I thought I fully grasped how Meteor’s components work together, but every time I had to go back to google keep looking for new answers.

IMHO Meteor can be really helpful for small projects, but it can become challenging to use if things get more complex. A guide with patterns and best practices from the community, driven by MDG is what we need.
Happy to help.

[cliffers]

Great job @sashko. Looks spot on!

[AndreasGalster]

From my point of view there is so much stuff mentioned there that I have no idea what it is even about. Which is a good thing. Hopefully this will also be suitable for beginners to give introductions to those topics rather than just giving an overview from the perspective of developers who already dealt with similar concepts! Thanks

[sashko]

I feel like there is a wide variety of information already on the internet for absolute beginners - tutorials, example apps, etc - and most of what I’ve heard is that there aren’t any good intermediate-level resources.

So this isn’t about building your first or second app, and it’s not a resource for super hackers; it’s for someone who has messed around with Meteor for a few days and wants to learn how to do things “right”.

Although we’ll still try to make the content as approachable as possible, and organize so that you get started reading the introductory bits without much knowledge.

[serkandurusoy]

I’d start off by asking @arunoda if he’d be willing to sign off his rights to bulletproof meteor and meteor explained literature over to MDG in a deal possibly including a sponsored by kadira link.

That would be a great kickstart to an awesome meteor library.

Also, a curated import from meteorpedia and @awatson1978’s cookbook along with some articles from prominent meteor bloggers getting 301-moved over here and we get a perfect picture of what we already have and what else we need.

[clayshannon]

Fragmentation (Android, anyone?) is a two-edged sword. Personally, I prefer sticking with the canonical, or in-the-box, approaches wherever possible (Blaze, MongoDB, etc.) To each his or her own, of course.

[sashko]

Also, a curated import from meteorpedia and @awatson1978’s cookbook along with some articles from prominent meteor bloggers getting 301-moved over here and we get a perfect picture of what we already have and what else we need.

One of the most important things we need for a good guide that “feels right” is a consistent vision and style. That probably means rewriting and adapting a lot of the content, but it sure is a great starting point. And I think it would make a ton of sense to link to other resources especially if we drew from them in the creation process.

[sashko]

So, I’m going to humbly suggest that there are two projects in the Meteor ecosystem that have already been working with rough analogs of the proposed charter: Meteor Cookbook and the Meteorpedia.

These are going to be extremely valuable resources while we are building this thing, and we should definitely link back where it’s appropriate.

As far as how it’s organized; some people may take exception to some of it’s assumptions; particularly around MVC, SQL, and a few other topics.

I think this is going to be the biggest thing for the new effort - I think we’ll need a large amount of editorial effort to make something that people can really agree and build on.

Challenges

APIs were moving targets, and when they changed, all the articles would get out of date.

That’s probably one of the biggest benefits an official guide can bring to the table. My hope is to create a company culture here at Meteor and for contributions in general that if you haven’t updated the guide for it, it’s not done.

Lack of officially-sanctioned flow-charts and architecture diagrams.

I think we are working on this - and it would be great if the guide contained some tasteful diagrams to explain core concepts and mental models.

Difficulty in finding the right ‘voice’ for articles. Should a topic be a FAQ? A checklist? A tutorial? A demo app? I suspect the ‘Guide’ will run into the same problem.

My plan currently is to model it exactly after the prior art: Rails guides, Django, Laravel, etc. Let’s start with catching up to the state of the art, and we can think about how to surpass it later.

People without animation / rendering / video driver / graphic design experience second guessing the MVC approach. More generally, people second guessing articles who hadn’t read their Knuth.

I’m not sure anyone really really follows “MVC” in the strictest sense, and I’m not sure it’s even a good idea. An app isn’t a video driver, nor is it a code snippet from The Art of Computer Programming. I think the React community has shown that there is still a lot to learn in the space of application architecture. While we shouldn’t adopt trendy stuff wholesale, it does make sense to take a look at the new tools we have available and think about how they can be best used to result in maintainable, testable, and reusable code. Perhaps the boundaries aren’t where we think they are.

[sashko]

I’ve put in some seeds to get the discussion started on some important topics, leading up to producing the first finished guide articles:

Issue: Collections and models

Issue: Application Structure

Issue: Should we recommend Blaze Components?

I’ve tagged a few relevant community members directly, anyone else also feel free to chime in!

[gabrielhpugliese]

Hey @sashko, many people often come to me when they have some CPU/load issues and turns out that most of the time is about publishing to much, doing sync stuff on publication or using observeChanges on big collections.
I think it would be nice to have a topic on this

[sashko]

Yeah I think that’s vaguely mentioned here: https://github.com/meteor/guide/blob/gh-pages/outlines.md#meteor-production-guide-deployment-monitoring-and-analytics

If there is some particular advice you think should go in there, please open an issue on the guide repository and we can discuss there!

[bobmonsour]

A proposed outline

This is fabulous! I had stepped back from doing work on my Meteor app due to other life intrusions, but have continued to follow developments. With all the changes since 1.0, this has me excited again to dive back in and develop a new app that I’ve been thinking about and I’m not brand new to Meteor, the Guide looks like a great idea. I love the approach you’re taking in both the charter and the outlines. Thanks loads!

[mitar]

I think each guide page/topic should have an open list of suggested technologies where anyone can submit a link to their package. And then community can upvote those submitted links. And once a link gets to the top, it gets covered in a guide.

I have the issue that this guide might create an echo chamber which would hide new players on the street. So it would be great for them to be able to submit the package and then early adopters could try them, vote for them, and motivate others to try them as well and so on.

So without a clear way how to deal with changing ecosystem guide will soon be full of old dinosaurs and maybe even not maintained one. (This for example happened to Discover Meteor in some aspects.) And then new people think Meteor has some shortcoming just because they are using a year old unmaintaned package (which was very popular at the time).

[sashko]

create an echo chamber which would hide new players on the street

I think that’s kind of the point. Keep in mind that this resource is squarely for people who don’t want to play with the newest technology and put together their own stack from the freshest new packages. People who are into that sort of thing will always be seeking out new stuff, and they will be the early adopters that can tell if something good is coming on.

But even so the plan should include having a set of links as part of each article to other options for doing similar stuff. For example, the Router page will hopefully also have a link at the end reminding people the Iron Router is out there as a second option, in addition to React Router and Angular’s UI router.

Let’s cross this bridge when we get there. If something starts feeling outdated in a few months, I’d expect people will open an issue on the repository and we can talk about it. If it turns out we need a process for this, we should figure one out when it’s clear what the issues are rather than trying to hit the target from a mile away.

In the meantime, let’s not forget about the benefits of relative stability - I wonder if there can be an effect where the maintainers of packages that are being officially recommended are more motivated to keep their packages fresh.

[AndreasGalster]

I was referring exactly to that. I know how to code an app with meteor. I just don’t know what I could be doing better. From a “non-coder’s” point of view of coding (designer who gets as much done as necessary) those best practices and common paradigms would be nice to see reflected in the guide to learn more about those things.

[rjakobsson]

Reading through the repo: THIS IS THE SUCH AN AWESOME PROJECT! Great idea @sashko!

[seba]

as far as Meteor Cookbook goes, I (we) had roughly the same Vision and Values as what you’re proposing.

Those values seem to be quite different when you say things like:

Listen, I decided to write the Meteor Cookbook with a focus on browser MVC structure…And it’s my prerogative to write the book how I wish.

• People without animation / rendering / video driver / graphic design experience second guessing the MVC approach. More generally, people second guessing articles who hadn’t read their Knuth.

It’s been some years since I read his books, but I can’t remember Donald saying anything about how a video driver is related to an architectural pattern like MVC, or anything about any of these 2. Would have been quite visionary of him.