I agree that there is potential for confusion around different API versions and outdated comments. I think the best way to solve this is to just have a button to flag something as outdated or incorrect, and also tag which version of the API a certain comment was made on. Then if we make a breaking change to some API, we can easily find the comments that might be outdated.
OK, looks like people are on board with 1. having comments and 2. having them be per-section rather than inline annotations.
A big decision here is:
Use a pre-existing drop-in comments system
Build a comments package for Meteor and use that
Arguments for (1):
Can be tailored to the specific use case and we can make any changes we want
Can be a package that people can use in other apps, and submit pull requests for new features
Arguments for (2):
Will be a lot of work to build in features an existing comment system will have, like moderation, spam filtering, etc
Anyone have any more points for 1 or 2? I’m trying to evaluate how much time I have to spend on this vs. the pros of having a specialized system.
As much as I understand using Discourse for these forums instead of a Meteor app, I think for comments it’s worth making the effort of building a package.
I mean, the whole selling point of Meteor that it makes it easy to build stuff. If we as a community can’t even build a commenting system and have to rely on Disqus, that doesn’t send a great message. Also as someone who uses Disqus a lot, I’ve been getting a ton of spam, which I doubt we’d get with a custom Meteor implementation.
And it’d take some work to adapt Telescope’s comments, mostly to decide what should be part of the package and what should be part of the app (whether it’s features, styling, APIs, etc.). But it’s definitely something I want to do anyway, the question is just how soon it can be done.
+1 for a per-api-method comment section using a custom meteor package.
The UI could be something like https://github.com/aroc/side-comments (with the extra features @sacha was evoking: votes, updates queuing, etc.). We also probably want users to login to their meteor account in order to post a comment. So there is actually a bit of work in both new functionalities and docs UI (should we even consider more ambitious new docs style? Improve Meteor documentation and styling)
In a nutshell, the tricky bit is that we are inserting our content to webpages served from other domains (ie. not controlled by us), and that requires quite a bit of extra permissions. The other way around would be wrapping the whole page in an iframe, and siphoning it via our own proxy server. The doesn’t require any extra permissions on the client side. In fact we support that approach, too (via https://via.hypothes.is/ ), but the Chrome extension uses the client side method.
As for your question, if someone compromises our plugin (for example, replaces it in google web store with a malware-infected version), then yes, I am afraid it would be capable of harming users, or at least stealing data.
What you can do about this is not using google web store, but build the chrome extension from source yourself. The documentation for that is there, too - but that also means that you don’t get automatic updates by us.
Thanks for explaining @csillag! I’ll take a look. Probably I’m not the only one concerned with such permission requests, so perhaps a similar explanation on Hypothes.is’ site could foster a wider adoption of this tool.
Interesting - I don’t think we at MDG know any more about what the docs should have than the users do, so I’m not sure if our list matters so much. Is there a good place we can make a list of features needed in order of importance? The first thing that comes to mind is a public hackpad but that doesn’t seem optimal for this kind of thing. Maybe discourse has some sort of polling plugin?
I spent two years collecting frequently-asked-questions from the mailing lists, and came up with a Meteor Cookbook that has 900+ stars. The table of contents may be a proxy for the list of features you’re looking for (albeit not ordered according to importance).
I’ve spent the last few months updating all the examples to Meteor 1.0, and have just started a sabbatical to write end-to-end tests for all the examples, and to update a bunch of the documentation with relevant API examples. I’m planning on using a basic weblog as the common example among all the articles; and have thought about using the weblog itself to create a searchable database of examples and docs.
If any of this seems relevant to this discussion at hand, please feel free to message me and we can coordinate efforts.
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.
