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:
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!
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?
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.
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.
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.
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.