Good drop-in comment system for docs.meteor.com


#21

There’s quite a few things we want to improve with Telescope’s commenting system. Some of the features to consider include:

  • Comment collapsing/queuing in the UI (so that new real-time comments don’t push down the one you’re reading).
  • Replying to email notifications to create new comments.
  • Voting.
  • Sorting/Filtering.
  • Nested comments (with collapsing/expanding of comment trees).
  • Comment drafts autosave.

Of course, these are all nice-to-haves, not core features. We’d probably start off with a much simpler comment system, and improve it gradually.


#22

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:

  1. Use a pre-existing drop-in comments system
  2. 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.


#23

@sacha how hard do you think it would be to adapt what you have now to fit into the docs app? Is it pretty separate from the rest of the app?


#24

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.


#25

Ok, I’m sold on a custom solution, even if it takes longer. I’ll probably get started next week.


#26

+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)


#27

Hey @csillag! I like the idea of Hyposes.is, but I’m a bit concerned about permissions requested by its browser extension:

  • Why does it need to be able to change my Settings… and Read and change All of my data…?
  • Is there a way to undermine the security of my PC in case the Hypothes.is’ extension gets compromised by some 3rd party?

p.s.: sorry for off topic, but I think this issue should be considered here. :wink:


#28

Hey @dalerka!

You can see our security settings here:
https://github.com/hypothesis/h/blob/master/h/browser/chrome/manifest.json


#29

@dalerka, continuing with my answer:

We need access to content setting permission because of this issue:
https://github.com/hypothesis/h/issues/634

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.

Choose your poison…


#30

+1 on comments per topic/api-method, I don’t see much gain from doing it per paragraph or per arbitrary text selection.


#31

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. :wink:


#32

@dalerka @csillag by the way there is a button to the right “Reply as linked Topic”, which lets you continue the conversation in a different thread.


#33

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).

Meteor Cookbook - Table of Contents

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.


#34

@awatson1978, amazing!


#35

bump! wondering if there’s any progress here?
some discussion in telescope chat too.
https://telescopeapp.slack.com/messages/general/


#36

I’m going to finish the Windows port first, then probably work on this!


#37

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.


#38

That’s great idea. Maybe it could even be compatible with http://readme.io ? I’ve been considering using that for Telescope.


#39

@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. :smile:

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.

What do you guys think?


#40

Do you think it will be bad if our docs are not hosted in a Meteor app?