While testing out the current tutorial I noticed that the tutorial way of doing things does not reflect the advices in the guide. That made me think about how this could be improved.
For example:
Meteor asks the new user to create files like: imports/api/tasks.js where the guide advices: imports/api/tasks/tasks.js
This topic is created in follow up on how to improve the tutorials after my testing in:
@sashko proposed a new topic here:
The tutorials repository can be found here:
Yes got that, indeed while thinking about it more and more things come up which make this quite complicated.
Took a look at how to edit the current version and yes that’s difficult. Totally agree that it should work, a not working tutorial is a very bad first experience.
Maybe somebody has experience on how to do this more efficiently?
The biggest issue with the current system is that we can’t easily take PRs.
Step 1 is probably moving the content into an open-source site and out of meteor.com, that way it will be much easier to contribute to the content. Any ideas about that? It could just be a Meteor app where we ship the client bundle statically, since there’s no server component.
This could be a good start: https://github.com/meteor/tutorial-viewer
Same as the guide I would expect them to be in an equal format. That also seems to be the most maintainable way. We do need pull requests, that’s the standard way so totally agree on that. The current way is not easy to improve.
But as I said I don’t have experience with tools for building tutorials and making sure they run each step also stable. What I would think of is just doing it reverse: take the code snippets from the md files. And then have a build process which runs them each step at a time to ensure they work.
But it sounds easier than it is in practice so if somebody has real experience on this that would be worth a lot.
Here’s the problem: how do you know where each code snippet should be inserted? Eventually you end up essentially rebuilding the git patch format from scratch.
Agree with this 100% having worked through the Blaze tutorial recently in order to recreate it with meteor-ui5. I was already on the fence about even having imports at all in a beginners tutorial.
The tutorial is also a marketing tool and there’s been thousands of new Meteor developers with varying levels of JavaScript experience who have embraced Meteor solely on the back of being impressed with how quickly and easily they could develop an app by following the tutorial.
Maybe we should make two versions of each tutorial, with one being super simple and attractive, and the other being more advanced.
Actually this could be an awesome idea. Basically, we cut down the tutorials to steps 1-6, and then replace the later steps with something like an “add-on”. So you build a super basic app, and then there’s a section like “adding accounts” or “adding security” or “adding publications”.
That will accomplish two things:
Note, @peter.roehlen and @akryum - I moved your posts to this thread, since they were about the tutorial.
Wow, interesting post here: http://info.meteor.com/blog/step-by-step-tutorials-with-git by you @sashko good reading materials!
Hi again,
This is a nice post, well done.
So, I’m the co-founder of a company that develops integrated learning systems for schools. Gamification is a large part of our software. One of the things we handle is the delivery of syllabus that varies in complexity.
Personally, my favourite way to deliver content of varying complexity, that needs previous understanding, is through the idea of “research trees”. A research tree is what you usually see in games, where over time, you get better abilities by researching stuff. See the image attached. Something like that.
We’ve explored a self-paced “research-tree” styled learning method wherein students can themselves determine how much they know, and what comes after their current level of understanding.
What do you guys think of delivering the tutorials like this? There can be three “divisions” - beginner, intermediate, advanced (“Eras” in the image above). The community decides what topic goes where, MDG validates. Each division can have a “learning outcome”. We can say that if someone has gone through all the “beginner” articles, they will be able to make a simple TODO App.
For instance, installing Meteor can go under “Beginner”; handling DNS, working with Redux can go under “Intermediate”. So on and so forth. There can also be further sub-classifications (or tags) like “UI”, “Security”, “Database”, etc…
There can be different “branches” (“Mining” in the image above), separating into “nodes” (“Masonry” and “Bronze Working” in the image above). For example, the branch “UI” could separate into “React”, “Blaze” and “Angular”. The “node” React could then itself separate further - each topic followed by another advanced topic.
Each topic will be linked to it’s own page where there will be a tutorial.
When you read through this you may think that this is obtuse, but once it is done, a visitor can see graphically - get a bird’s eye view - of what needs to be learnt.
PS: We can mock this up real easy using D3 - Collapsible Tree · GitHub. This is easy to do.
All this is trivial with a research-tree.
Also, @MDG, can the community have it’s own sub-domain? Like “community.meteor.com”. It can be a place where efforts of different community teams merge.
Someone would have to take the lead on this and be responsible for bringing everyone together, and directing the efforts of different teams.
You are concerned about beginners, please also think of those who are trying to dive deep into Meteor.
For instance, I had a very hard time figuring out how to get different kinds of login services to fit into the whole Meteor paradigm. Then there was the time when I had trouble with MupX and had to scourge the forums.
There have to be some resources also dedicated to those people who want to explore more advanced stuff. Just simple Todo apps won’t do for many.
Just a note: A company I like very much that has an incredibly rich resource of information is IBM. Check http://www.research.ibm.com/articles/. They have articles, often about IBM products, for people at all stages of understanding.
I’m sure we can set up a subdomain in 2 seconds, but what kind of web presence do we want there? A static site generator deploying from Git? Or something more complicated?
BTW that might be a topic for this other thread: Community Involvement Setup
I’m a bit worried about systems that sound really ambitious - is there a set of steps that will get us to a situation like that incrementally? How will we maintain all of these different divisions, and make sure they are internally consistent?
Perhaps you have experience in this, but it’s paramount that whatever system we decide on is easy to iterate and improve.
I don’t think the graphical challenge of displaying the steps in a tree is the main problem here - that’s something we can easily set up. I’m interested in hearing about the workflow of writing this content, keeping it up to date, and improving it over time.
While I think this is a real issue, I don’t think a beginner tutorial is the right place to do that. IMO that’s more something that should go on Stack Overflow Documentation or the Meteor Guide or similar.
I would be interested in starting a new meteor app project to bring the tutorials to the next level. 
After reading this article, I was wondering how we could update the repo without breaking the convention of using the commits as the steps. Let’s say we want to update some code, how do we do that? do we recreate a new repo entirely to have a clean commit list?
You can use git rebase -i to edit a specific commit in a repository.
