Hey, I’ve heard some comments from people here about the lack of good code samples and context on the official Meteor documentation website.
I’ve been thinking of testing out a comment system that will let people post information and usage examples for different API methods on http://docs.meteor.com. For example, people could link relevant questions on Stack Overflow, screen casts, blog posts, etc.
One option is to build a comment system from scratch with Meteor, but it would take a lot of work to build in moderation features, formatting, etc. I’d like to use an existing comment solution if at all possible.
The only good drop-in comment system I know of is Disqus, but from what I’ve seen it doesn’t have good support for code snippets which is pretty crucial. Does anyone know any other good solutions for this use case?
More high level, though, why not open the Meteor Docs app to the community so we can build the tools we need? It can still go through you guys, but adding a commenting system with very specific features (eg. being able to comment directly on a paragraph of code, or reference the Meteor forums, etc) seems like the kind of thing you’d want to build custom anyway. It’s not something the core team should spend too much time on, but it’s perfect for, say, someone like me with an hour or two to spare here or there.
Yeah, it’s hard to contribute to the docs (or any specific area of Meteor, really) if there isn’t a list of things you guys need doing. I wouldn’t want to spend a few nights working on a commenting system if I didn’t know that’s at the top of your list, for instance.
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?
Hey guys, here is the simplest way (IMHO) to augment the docs with some relevant info:
there could be a “Relevant Links” pane for every API item in the docs. This pane could be styled as collapsed below or aside the paragraph explaining a piece of API or a concept, perhaps with a tool-tip like: “help us improve the docs by submitting a PR with a link which you think explains this part of docs.”
The community members can simply submit PRs to the docs with links to this forum, SO, MeteorPad, Hackpad and perhaps even some blogs. Yes, it is more complicated than posting a comment but may help to keep the docs cleaner and better. And we have this forum for discussion and commenting.
the MDG can easily review such PRs as they will only change the Relevant Links pane and not the main body of docs.
Just my 2 cents (until a good drop-in per-paragraph commenting system is developed using Meteor )
I like the idea of a comment system. Pull requests are much more serious business.
The comment system in PHP’s doc has saved me a bunch of times, specially from really edge cases you wouldn’t find in the documentation; but it can be overwhelming and some times repetitive. So a comment system with some sort of voting on the best comments and hiding the others and maybe turning them into community-wiki to keep them updated like Stack Overflow does would be nice.
Just thought of a yet simpler and efficient solution (IMHO):
for every API item in the docs MDG can simply create a link to a dedicated topic (or sub-topic under Meteor Docs Explained topic) on this forum such as: More about this API here…
This forum (Discourse) already provides all the necessary tools for us to discuss things, share code and links to external resources.
Newcomers to Meteor Docs will easily learn about this forum too.
Sounds really cool. I’d love to see something similar to the Medium commenting system. Unobtrusive and right where you need it. I think there is something similar in the Discover Meteor book, but it is not as granular.
But I think there must be a moderation aspect to keep the docs from becoming too bloated with 20 annotations for async eventually. I am no friend of the PHP docs.
Here’s another crazy idea - how about each paragraph gets an official hashtag like #bindenvironment so that every developer has a good convention of how to search and post relevant information? I know that the existing code could already be used, but who thinks about using it as an hashtag - rather integrate the “right” tag directly in the docs and it becomes much easier to discuss that part of the docs.
Yes – I agree about the commenting-per-paragraph. That would be great, but I’d suggest a further refinement similar to commenting in Microsoft Word, where you can select a shorter phrase. That would really help pinpoint ambiguous writing. I use the diigo browser extension for personal annotation/collection of web content and really like it. It also has a group feature. cc: @sashko
I’ll definitely check it out! Now that the release candidate for windows is out, I’m taking a break for a few days to work on docs comments and maybe some blaze stuff.
@csillag - my concern with sentence-level annotations is that they might break if we change the text or structure of the docs page. Comments on a per-api-method basis seem to be a lot more maintainable since that method will always exist. Does Hypothesis solve that somehow?
my concern with sentence-level annotations is that they might break if we change the text or structure of the docs page. Does Hypothesis solve that somehow?
In a nutshell, as long as the referenced text remains even vaguely similar, and especially if the context (ie. the text before and after the interesting part) is still similar, we can anchor annotations back to where they belong, even if the structure of the page has changed.
Another benefit of per-method comments is that they centralize discussion in a smaller number of locations. It seems to me that having 4000 separate comments on one word/sentence each will not be as useful to people as 100, one per API method or docs section or something.
One more question: is there a way of manually identifying annotations that have been lost due to text changes and reattaching them somewhere?
Same experience here. While it is certainly not perfect, it seems to have worked very well.
I think each topic needs to have its own comments grouped together.
Word by word annotations seem overkill and I am struggling to see how they would translate into formal documentation. Wouldn’t it become a mess with contributors adding comments all over the place?
With the PHP docs, often I would just ctrl+f to see if someone is getting the same error message as I and to see what the fix is. If there were security issues with a function, people would explain alternatives and that comment would usually get voted up to the top. People providing bad advice get voted down, and through moderation those comments can be deleted/hidden.
@sashko, we have an orphan annotation roadmap item for this. Our objective is to use the Internet Archive’s “Save Page” service to prompt them to crawl a page each time it’s annotated. We can then use the memento syntax to fetch pages where we can no longer reattach annotations, and offer to reattach them to the archived version of the page instead.
I also think per-section comments would be better (and a lot easier to put in place) than arbitrary Medium-style annotations.
Maybe we could work to extract Telescope’s comments feature into its own package? If we had some kind of standard “meteor-comments” package, other people could also build dedicated packages for whitelisting, moderation, etc.
Having a telescope style comment system per API would be ideal. It’s a lot less overhead than having to fork and send a PR every time you want to add something. I’d prefer a clean commenting section with upvotes than a hodgepodge of annotations on the main content - that seems mostly relevant for marking up corrections/opinions, as opposed to space for examples and other real world illustration of the api.
And telescope’s meteor-comments as a package would be awesome too, i could certainly use that on other things!
one other point is versioning and whether comments should be tied to a specific version of an API. meteor has been pretty good about this so far, but i recall Angular removed comments because of confusion around versions and incompatible APIs. Maybe that was just another angular problem…
)