As I’ve been reading through posts here, reading up on questions, replies, confusions and frustrations, I tend to feel there is a common problem with both meteor core and atmosphere packages and that is proper, structured, extensive and extensible documentation.
This post and effort to get the official docs to where we imagine it will be, through a comments system, will in no doubt be invaluable to every one of us.
That being said, can we not perhaps extend our efforts to a form of a complete documentation package that both meteor core and packages can utilize.
A documentation structure and a software system to maintain it, that is common among the whole meteor ecosystem, would be a great aid in creating a learning environment that aids and speeds up the efforts in embracing meteor for both newcomers and pioneers alike.
That would open up the possibility - thanks to DDP.connect() - to even consolidate docs together, or through a central hub like atmosphere to allow us to create ourselves accounts and our own document libraries. It would be great for example for me to create a new doc library, as I start a new project, that gathers up the documentation for all the packages that I will be using in that project. I could annotate and comment within the context of my project, but will simultaneously have contributed to the overall documentation.
I don’t know, I kind of digress there, and maybe not. Maybe, this would be a great vision for a meteor documentation ecosystem.
@sacha I agree. readme.io looks awesome. I would say it would be awesome if you moved the telescope docs over to there.
@sashko What about moving the docs to a system like readme.io? According to their pricing page, they would love to host open source projects for free.
It already handles things like comments / suggestions and makes it easy to version the docs rather than having to deploy separate instances like @glasser had to do for people to see the 1.0.4 docs.
And it allows you to have separate internal private docs if need be.
@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.
