I don’t have an actual project yet, but that’s the direction I want to move in with Telescope. So maybe we can coordinate so we can replace both comment systems with a common one down the road?
OK, I’ll refactor my thing into a package to start!
I created a hackpad for discussion about UI polishing, flagging, editing etc. If that’s not helpful, let me know and I’ll get rid of it. I asked a couple of questions on that pad. I’ll play around with the code, but it might be a little over my head at this point.
let us know when there’s a package!
interesting discussion and other examples on HN about using rapgenius for code commenting. a bit different but relevant.
https://news.ycombinator.com/item?id=9336297
personally i think the comments are the meat and the source/function just become a skeleton to hang the comments off. if you end up with pages of comments and examples for each function that would be awesome, not a few popups here and there.
one code-specific thing tho is that each comment should be tagged with the API version its relevant to?
Yeah right now the idea is that it’s tagged with the api version that was current when the comment was made.
So Hypothes.is could be made into a Meteor package, one would just add it to the page and users could start commenting/annotating. You would not need a browser plugin. (So no permissions issues.) And annotations would be stored on the site.
We used their code to do something similar at https://peerlibrary.org/ to annotate PDFs.
Hypothes.is looks like another annoying popup annotation thing? I’d like to see the comments to be a lot more front-and-center than being hidden away in a popup - more like hackernews where the comments are the content. not the function they relate to. afai understand, the goal isn’t annotating the source, more comments on the APIs
Also its a chrome extension you have to install, so people wouldn’t see anything without doing that (or using a different browser)?
-2 imho.
2 Likes
I think a comments system can also address the problem described at Coping with architectural option overload but that of course requires another section on the docs. Somehing like “patterns”.
I don’t know if it is the best place, but I’d certainly like it to be.
Similarly, I’d love to see atmosphere implement the same comments system. That would also make it easier for everyone to contribute on package documentation in the form of comments.
@sashko I like what you have so far. Its a good start. My only question is, where do comments about undoucmented api’s go. How do we request missing documentation on an api per my post here - Documentation update suggestions on meteor features
I have started developing a little comments package https://github.com/ARKHAM-Enterprises/meteor-comments-ui. It’s not that great yet, but I’ll continue developing on it after my final exams.
2 Likes
As food for thought, I have created a Meteor Doc project in UtopiaEdit.
(please ignore the wrong API titles, I did this quickly)
For this kind of application, the Proposals tab could be changed to another name, or turned into multiple tabs for different kinds of items (links, discussions, etc.).
I really like the comments capability on the guides and wondered why it isn’t on docs… A quick search turned up this year old thread at the top of the list. Is it time to revive this? Or maybe with all of the recent rework it’s actually already in the works and we’ll see it any day?
I have found documentation comments in other projects such as PHP and PERL to be very valuable. Maybe, with time, they could add some of the fundamental details missing in docs.meteor.com.
1 Like
Sounds like something we should do asap! Adding threads just like we have for the guide be rshould eally easy.