@sashko I don’t think it would be bad if it wasn’t hosted in a Meteor app. You’re just utilizing tools that are already built so that you guys can focus more efforts on Meteor platform itself.
I personally don’t see that as a problem. Utilizing something like readme.io could save you a lot of time in the future.
One of the things I see as a big benefit is that people can view previous Meteor versions docs. So, if you have an app that isn’t ready to be updated to the latest version of Meteor (seems like a rare case), but if it is the case, you can look at the way certain things were done in previous versions. For example, from 1.0.3 to 1.0.4, the template hooks changed like created -> onCreated, but if you are maintaining an app in 1.0.3 and don’t remember what the hooks were, using onCreated would not work.
If you have to host certain things like docs on other platforms just so you can spend less time managing them, i’m all for it. Take as much time out of maintenance / grunt work and put it into development time.
I am so much in need for a better subscription system (see here), a better Blaze with no context, UI components with attached data and animations, a built-in client-side basic routing feature and a ‘Match’ extension to support db/form schema, that I would hate that MDG spends time on anything else :- )
No way, it is definitely not bad! What next? Do we drive a “car made by meteor” to work or cook in “meteor pot grills”?
Joke aside, you guys should take as much time as you need to deliver us the core and not feel bad about using 3rd party products/services. After all, you’re not writing your own version of node, so why write your own version of a docs system?
That being said, I think we (the community) can perhaps come up with an innovative docs solution like the one I described a few comments back above. If the idea gains enough traction, we go for it. If it does not, we’ll wait/look for the next idea that may gain traction.
@sacha I’d like to hear your take on that idea as well.
I think using Readme.io is fine, but at the same time I think the more real-world Meteor projects MDG can hack on, the better. So I liked the idea of Meteor docs and a commenting package. Eating your own dogfood and all that.
But maybe that role can be filled by something else, such as Galaxy for example? So I don’t see any other downsides to using Readme.io.
I think having a nice flexible and reusable documentation system for Meteor as well as meteor packages could be great to establish a distinctive meteor “look and feel” where visitors can immediately think “hey, i know this, this is probably something from or for meteor”.
A distinctive look and a simple and good useability / readability could really transport the intended professionalism whilst also remaining a humane and positive experience - and that is what meteor to me is all about, powerful with a simple, friendly API.
I loved the basic readability, colors and style of the easySearch docs when i stumbled over them recently, although I don’t know if it’s a template or a doc generator / package or custom built: https://matteodem.github.io/meteor-easy-search/getting-started/
Anyways, I think it’d be great to have a cool solution to write docs for our custom meteor packages and projects as well.
It would be nice if atmosphere used the same generator so the packages could use the same documentation system (and comment system if it’s added to it).
I wish there a way to detect which API code is used in the comments and highlight in red to those lines similar to Github changes as outdated/depreciated.
And video like Laracasts would be nice with amazing instructor for clearer explanation like how exactly dependency.hasDependents() works in a few minutes through demonstration than can’t figure it out.
I know there are EventedMind and some free video tutorials, I still very much like the way how Jeffrey makes Laravel interesting. MDG should start the netflix course.
One of the best quote I saw: “Tell me and I forget, teach me and I may remember, involve me and I learn” - Benjamin Franklin
Okey doke, I have started working on a custom docs comment system. If you would like to participate in active development over the following week, take a look and submit some PRs!
I think the commenting itself works well now, but it needs a lot of UI polish, and boilerplate stuff like flagging posts, editing comments, etc.
You can run the app just my cloning this repo and running meteor in that directory.
That did the trick (pretty obvious on second thought). Thanks for being patient with the noob.
In terms of discussing UI polishing, do you want to discuss that here or should I open an issue on Githhub? This is mostly a learning experience for me, but I might be able to help a little bit. If that wouldn’t be helpful, please let me know, and I’ll just play around with it locally.
@sacha on second thought, I think it would be a lot better if we could make this part of some generalized commenting package - I think that might actually reduce the maintenance burden on MDG’s side. Do you have some project like that already spun up, or would this be the beginning?
