dvc.org
dvc.org copied to clipboard
iterative
Adding a commenting/contribution/bug report feature
utteranc.es is a commenting system that ties Github issues with web pages. We can include it in dvc.org to increase user engagement and get feedback in our documentation.
It's a lightweight JavaScript file and a Github application working together. We can also reproduce it by rewriting, it's not particularly difficult technically but I don't think we should reinvent it.
Upsides
- Increases the user engagement and feedback. Users won't need to visit Github to discuss the documentation. I believe the most of the user input is lost because of the need to open another platform. (Discuss, Discord, Github etc.)
- In Get Started pages, we'll be able to see what to include and what to remove.
- In the User's Guide, we'll see if they don't understand something and we have missing features to tell.
- In the Ref pages, we'll get bug reports and feature requests.
- In Use Cases, they may ask for more cases suitable for their environment.
Downsides
- It may cause some spam or distraction. Commenting requires Github account, so I don't think that'll be much of a problem.
- Eventually each page requires an issue created here. This may be good as we won't need another place to keep tabs on user comments, but also can increase the number of issues considerably.
- Depending on utteranc.es may require some customization if they add incompatible changes. (Unlikely)
- We'll be showing Github issue comments in our pages. This may lead to some license issues. (Unlikely.)
- Renaming pages and redirecting in documentation may become a bit more complex.
(Please add any downsides you can think of here.)
Discussion points
- Is this something feasible and maintainable? @julieg18 @rogermparent
- What would its effects be on developer/user relations? @jendefig @flippedcoder
- What problems may arise in issue management? @jorgeorpinel
I think making it easier to get feedback from users is ALWAYS a good thing. I think this is a great idea! I was confused about what it was from the docs meeting and the page, but understand now. I'm in favor, but have a bit of concern what it will look like with a big string of comments following and maintaining it. But having users see a string of positive comments and even negative ones that are quickly addressed by the team will be a positive to our Community! 👍🏼👍🏼👍🏼
Is this something feasible and maintainable?
Seems like a normal utteranc.es install is pretty much just a client-side script, so I'd say it's easily feasible and maintainable. It'll take a bit of initial effort to add it to the site and make it look decent, but from there it seems to mostly be hands-off other than comment moderation.
Sounds like we definitely want some sort of commenting system to catch users who wouldn't get to our support/community channels otherwise. And adding some UI plugin seems like the easiest route. But I'm not sure about utteranc.es TBH.
Commenting requires Github account
Can't this contradict the intention? (catch users who wouldn't get to our support/community channels otherwise)
can increase the number of issues considerably problems may arise in issue management
Yep. Do we want a never-ending GH issue for each page people comment on? May look bad for the repo too. We'd have to create a separate dvc.org-comments to keep things clean.
In Get Started pages, we'll be able to see what to include and what to remove.
Please elaborate. (How?)
In the Ref pages, we'll get bug reports and feature requests.
We'd still need to create independent issues and PRs for those though, right? Or ask users to do so. So the GH integration may not be helpful for us.
Maybe https://disqus.com/ ?
Can't this contradict the intention? (catch users who wouldn't get to our support/community channels otherwise)
Umm, relative to what? Assuming our audience has Github accounts is more plausible than they have Discord/Twitter/Google accounts, I believe. Other than plain old email signup, this seems the most common way for authentication.
Do we want a never-ending GH issue for each page people comment on? May look bad for the repo too. We'd have to create a separate
dvc.org-commentsto keep things clean.
I didn't really check but comment issues could be closed (and they still show the comments) and can have a separate label. We can use a separate repository too. That's fine.
Instead of checking another place for comments, we can create new issues directly from Github and follow their history. This is a (IMHO big) :+1: for Github dependent system.
In Get Started pages, we'll be able to see what to include and what to remove.
Please elaborate. (How?)
If we get a (sensible or not-so-sensible) question for something we tell in GS pages, then it's either too much or too little :) I believe, our goal in GS pages is to avoid questions by presenting the exact amount of Get Started information. (We can't really avoid questions and we shouldn't, but it may be a nice objective measure.)
We'd still need to create independent issues and PRs for those though, right? Or ask users to do so. So the GH integration may not be helpful for us.
We don't need to create new issues for comments. Utteranc.es does that. For new issues bug reports, etc., we can "create new issue from comment" feature in GH to keep the reporting history. Users can be asked to create issues in the core repo as well, but the amount of feedback we get will probably increase.
Maybe https://disqus.com/
There are alternative systems, but Disqus is not one of them. It became a user-hostile system for some time. We can be protested just for using it.
Seems like a normal utteranc.es install is pretty much just a client-side script, so I'd say it's easily feasible and maintainable. It'll take a bit of initial effort to add it to the site and make it look decent, but from there it seems to mostly be hands-off other than comment moderation.
There may also be upstream changes to follow, but I've added to my blog in about 30 minutes. (My personal aesthetic bar is not that high. 😆 ) I believe it won't take much time for you to customize.
Comment moderation is mostly on us.
but have a bit of concern what it will look like with a big string of comments following and maintaining it.
I also don't know if it will look good if there are more comments than the content itself. We can hide the comments, delete them, move the issue itself and restart from scratch. I can't decide before seeing how popular it will be.
Assuming our audience has Github accounts is more plausible than they have Discord/Twitter/Google accounts
Pretty sure it's safer to assume most people use Twitter or Google. And I think Disqus has several other sign-on options.
Instead of checking another place for comments, we can create new issues directly from Github
When you say another place what are you referring to? The original commenting location would be a page in dvc.org, right? In which case Github is the other/extra place.
For new issues bug reports, etc., we can "create new issue from comment" feature in GH to keep the reporting history.
Woah I didn't realize that's a thing, nice!
There are alternative systems, but Disqus is not one of them. It became a user-hostile system
Can you explain how it's user-hostile, perhaps with some real-life example? What alternatives would you recommend? Thanks
hide the comments, delete them, move the issue itself and restart from scratch
I'd be opposed if it needs that much manual maintenance. It should only load a number of comments by default. Maybe add it in a PR so we can try it?
Pretty sure it's safer to assume most people use Twitter or Google. And I think Disqus has several other sign-on options.
Disqus is an adware and those login options are not for people cautious about privacy. Asking the reader to log in via Google/Twitter etc. signals that we endorse them. Although I don't have any personal issues with this, I can see why people are opposed to it.
When you say another place what are you referring to? The original commenting location would be a page in dvc.org, right? In which case Github is the other/extra place.
The comments will be seen beneath the content in dvc.org. The user won't have to navigate to another URL to see the comments. Integrating, e.g., discuss.dvc.org may also be possible like this, but it requires more work.
Can you explain how it's user-hostile, perhaps with some real-life example? What alternatives would you recommend? Thanks
I used disqus in the past, until they were sold to an advertisement company that monetizes the user data. It's also slow and bloated.
https://areknawo.com/top-6-disqus-alternatives-for-technical-blogging/ lists some alternatives. I also used Isso in the past. It's a bit of a hassle to keep a dedicated server for comments but doable. The reason I'd like to keep the comments in Github is not introducing another platform on top of Discord, Discuss, the email group, ... (Thinking this, maybe there are locations that I'm still not aware of 😅 ) Also we won't have to mind the security of another server.
I'd be opposed if it needs that much manual maintenance. It should only load a number of comments by default. Maybe add it in a PR so we can try it?
It loads the issue comments. I don't know how many of them but it's no different than maintaining an issue here. Also, Github issues load fast, I don't think they'll slow down the pages.
I'll create a PR. Thank you.
Resurrecting this. Was just having a convo with Mert and he said it would be great to have the ability to like/heart/etc. a blog post on the blog itself.
Yess, we thought why DVC blogs don't have a like/heart or clap button like medium. It must be so easy for the web team 😄 It will show us how much engagement we are getting.
Also maybe view counter for blog writer and @jendefig. (I don't know if this exists) View counter feature would show you which content is viewing a lot and which one is less.
These 2 features came to my mind right now, I will follow this issue regularly and try to be more productive about issue ✨
View counter feature would show you which content is viewing a lot and which one is less.
IMHO this looks a bit unprofessional. We already get this information from the analytics.
I need some input from @julieg18 and @rogermparent on where to embed the utteranc.es JS. After that, we need to decide whether to put platform to the commenting box to all the pages or a subset, like the blog or GS. (@shcheklein @jorgeorpinel ) We need to create another repository to store the comments and add utteranc.es as an app from GH marketplace.
I would think something like utteranc.es, should we embed it, would either go above, under, or replace the current discuss.dvc.org comments on blog posts in the src/components/Blog/Post component, toward the bottom.
Speaking of which, would most of the issues that utteranc.es would be introduced to solve also be solved by making it possible to post to discuss.dvc.org from within the page? Not sure how feasible that is, but if it is it would allow us only maintain the single commenting mechanism we already have.
It also seems utteranc.es doesn't have the ability to have reactions (clap, heart, etc.) on the article itself. https://giscus.app/ is a very similar application that does have this feature, and also uses GitHub Discussions so it won't pollute our Issues either.
Ah, thank you @rogermparent . https://giscus.app seems like a better option.
BTW, we don't use GH discussions for dvc.org repository, so we don't need another repository to store these either.
IMO having fewer channels to check the discussions is better. If the current discuss.dvc.org could be embedded in the site, I wouldn't hesitate to use it instead of these. Nevertheless, I believe something that can be used within the site will probably replace all other channels in time.
WDYT about embedding https://giscus.app to dvc.org @shcheklein ?
The only concern that it will ask people to authorize it (or in case of self-hosted thing - some app we would create) to have access to your account:
There will be questions like this I guess:
https://github.community/t/why-does-this-forum-need-permission-to-act-on-my-behalf/120453/2
I'm not even sure how does it propagate my actions (likes for example) if they don't ask for permissions editing things.
But otherwise - it looks nice and promising to me. And I like that it is built on top of GitHub - Gitops for comments - all the stuff that we like :)
would either go above, under, or replace the current discuss.dvc.org comments on blog posts
It would be ideal if we could find existing (recent-ish) Discuss posts that relate to docs articles and add an automatic "Common Questions" section at the bottom of the page, at least for the more feature-specific content (references, many guides). Just a thought
btw both utterances & giscus use GH issues to host comments so if we add a button "go to GH issue to comment" then we won't need "Sign in with Github -> X would like permissions to scary things"
Does it require app permissions on user's account really? @casperdcl I thought it's just for us to install, the commentors should only be logged in I believe. I need to test this belief, though.
Does it require app permissions on user's account really? @casperdcl I thought it's just for us to install, the commentors should only be logged in I believe. I need to test this belief, though.
Just tested it with sites that use Utterance and Giscus. Both apps ask for permissions:
Ah, thank you very much @julieg18
I'm ambivalent on this, the "act on your behalf" permission looks really scary. @casperdcl 's idea of putting a link looks more feasible but could we show the discussions beneath the page?
casperdcl 's idea of putting a link looks more feasible but could we show the discussions beneath the page?
yes discussions are visible on-page without logging in/permissions. It's just if you want to post/add to them; you either need to (1) grant scary permissions OR (2) go straight to the hosting issue and comment there.
I'd suggest replacing the "Sign in to comment/Sign in with GitHub" box/button with a "Go to GitHub thread to comment" button.
I'd suggest replacing the "Sign in to comment/Sign in with GitHub" box/button with a "Go to GitHub thread to comment" button.
Good idea, but since all of the commenting code is inside a iframe we are unable to edit its contents 🤔
inside a
iframewe are unable to edit its contents
ah well it's all opensource so we could just fork & modify :)