New MDG project: The Meteor Guide

Hi everyone!

There has been a ton of discussion here on the forum about MDG interacting with the community, sharing the vision for the framework, the need for better docs, better support and publicity for important community packages, etc.

Let’s get started!

Today, we’re spinning up a new project called the “Meteor Guide”. The idea is that it is will be the best resource to know the officially supported and recommended way to accomplish your goals with Meteor.

Let’s try a new thing - we’ll do it totally in the open with discussion and contribution from the community starting with the very first stages. I don’t have anything concrete to show you yet. What I’ve got is:

  1. A charter
  2. A proposed outline

I’m here to get your feedback. Go and read the charter, and let me know what you think.

83 Likes

This is great, Sashko! Really. Can’t wait to see how this fills out.

2 Likes

Finally, a comment! Phew. Thanks for the support :smile:

I expect it will be easier to people to contribute once there are some parts filled in, and we’ve got a live site. Hope to have that within the week.

1 Like

More than happy to contribute! Great idea :slight_smile:

This looks great, I would love to contribute to this.

I am super interested in helping out, especially as someone who has written docs and I am not even sure how/where to submit them at the moment.

I have plenty of ideas/opinions on many of the topics listed in the outline :slight_smile:

4 Likes

Looks like the exact thing Meteor community was missing so much. Love the idea! <3

2 Likes

That’s really cool, it’ll be awesome to have a go-to, recommended best practice for each of these points. I’m really looking forward to seeing where this goes!

1 Like

Can’t wait to add ESLint-plugin-Meteor to that list. Looking forward to contribute as well!

Right now, there isn’t anywhere to submit docs - I’m going to build that out this week. For now, I’m mainly looking for feedback about the vision of the site and the outline.

The outline has a bunch of great topics. I’ve opened an issue for discussion already.

My other question is, do we need a policy on commercial linking? i.e. I product https://mastering.meteor.js, can that be linked anywhere? @rahul sells consulting services, @arunoda has a performance monitoring and stats platform. I think the content should stay free of that stuff to avoid issues. Should I open an issue for discussion or just keep that here?

2 Likes

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.

I can’t speak for Meteorpedia, but as far as Meteor Cookbook goes, I (we) had roughly the same Vision and Values as what you’re proposing. Meteor Cookbook is the result of 2 years of working with the Meteor NY community as a NY Meteor Meetup organizer. It’s got 1400 stars on GitHub, and 31 contributors.

And to be perfectly frank; even if I’ve been the primary curator of the project, the vast bulk of all the recipes, snippets, and code samples are from other people. It truly is a community effort. I’ve merely been acting as a secretary and taking notes.

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. That’s fine. I’m not claiming it’s the only approach. Merely that it’s been a popular and pragmatically useful one. And it sort of represents a distillation and record of 2yrs of community contributions from the NY community and Meteor Talk/Core mailing lists.

So, yeah. This isn’t the first time the community has approached this kind of resource. And I guess that makes me want to ask questions like: How can we leverage past efforts? What can we learn from the attempts at using GitHub and dogfooding a Wiki to create this resource? How does Angular and React integration effect previous Blaze-oriented attempts at writing similar guides and cookbooks? etc.

From my experience working on a similar project for 2 years, the biggest challenges were:

  • APIs were moving targets, and when they changed, all the articles would get out of date.
  • Lack of officially-sanctioned flow-charts and architecture diagrams.
  • 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.
  • 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.

Anyhow, I’d guess that Meteor Cookbook can take care of about 20% of the proposed outline, with an article, code recipe, or applet. Meteorpedia could probably take care of another 20%. I don’t envy you and the technical writer who will need to write this so it works with Blaze, Angular, and React.

18 Likes

Great idea! I’ve just gone through this the last few months and compiled my own resource guide into OneNote.

There’s some good resources out there but also a lot of landmines in the forms of outdated projects etc as mentioned above.

On the vision: Awesome. A trusted and centralized documentation source is very much needed. There will be challenges and you / we will just have to work through them and solve them!

On the outline: Great topics. The missing one for me is SEO and social meta tags like OpenGraph and such.

Let’s open issues to not clutter up this thread.

This looks great, excited to see the initiative. The outline has many topics I’ve run into over the last year or so, having this in a central location would be awesome.

Awesome sashko. I’m more than happy to help.

1 Like

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

I can work on these.

Great stuff.

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

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.

3 Likes

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