Add comments to docs

Tracking progress of enabling Discourse comments in docs.

https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963

How would this work with versioning?

Nice question. cc @SeanPackham @sytses

@connorshea @axil we aren't doing versioning.

You either have a specific version of GitLab CE or EE installed on your server and therefore have the correct docs or you are using GitLab.com which points to the most up to date docs.

we aren't doing versioning.

@SeanPackham we don't now, but we plan to in https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/5. If we are aiming at dropping /help support which is built into GitLab and focus on the portal, we need to have some kind of versioning.

or you are using GitLab.com which points to the most up to date docs.

.com also runs on a specific version and if we are deploying docs.gitlab.com from CE/EE master, we tend to have newer documentation than we support. That's what we are trying to solve with versioned docs.

Discussion in https://gitlab.com/gitlab-com/gitlab-docs/issues/16

@axil didn't we have a discussion with @sytses where we decided that both internationalization and versioning were an unnecessary complexity?

I see help is gone from the side menu in 8.14, what is the suggested way to get help for your GitLab install? I thought helpin GitLab pointed to the local server docs instead of docs.gitlab.com because of firewalls and versioning.

didn't we have a discussion with @sytses where we decided that both internationalization and versioning were an unnecessary complexity?

AFAIR we talked about the complexity of deploying another branch than master to the docs portal, not abandon the versioning idea altogether.

I see help is gone from the side menu in 8.14,

It was moved under the profile dropdown, it's not gone :)

I thought help in GitLab pointed to the local server docs instead of docs.gitlab.com because of firewalls and versioning.

That's the idea, yes, but we discussed this in https://gitlab.com/gitlab-org/gitlab-ce/issues/18739 and we kinda agree to drop the built-in help page in the future.

I'd like to possibly include the generated Nanoc site in the Rails app rather than rely on the docs.gitlab.com site being up and working, but I'm not exactly sure how we can accomplish that.

Axil says he was told he couldn't hide the comments behind a "Load Comments" button, I don't really understand why when that'd help to make the site load faster and the page smaller. Not to mention most people probably wouldn't want to see the comments, my understanding is that it's primarily for feedback. Thoughts?

@SeanPackham @sytses insist on having the comments section shown by default. I don't want us to end up like PHP where the documentation is 3 paragraphs and then the comments make the page look like there are 43 (https://secure.php.net/manual/en/features.http-auth.php). @connorshea worries about load times :)

We need a unique identifier for each page like we use in https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/source/includes/blog/comments.html.haml#L5-6

mentioned in merge request !39 (closed)

So, Disqus:

• Loads the comments section only after you are at the bottom of the page (Connor's concern)
• Only shows the highest rated comments at a given point of time, so it doesn't clutter the page (my concern)

Let's enable them by default now and see how that goes :)

If we could find a way to disable them on certain pages that would be great. I wouldn't want comments in index pages.

@axil we could use frontmatter to disable them on certain pages.

marked the task Create new site under https://disqus.com/admin/orgs/1931444/gitlabinc/settings/general/ as completed

Thinking about this a bit more, I think it makes sense to host the docs comments under our forum which runs Discourse and it supports this functionality.

• https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963
• http://www.railsonmaui.com/blog/2014/09/27/updating-to-jekyll-2-and-discourse-for-comments/
• http://academy.ghost.org/how-to-use-discourse-for-commenting-on-your-ghost-blog/

@axil I enabled it for a Jekyll blog (a long time ago) with a JS snippet, should be easy to do to docs.gitlab.com:

This is the include file: https://gitlab.com/marcia/blog-test/blob/master/_includes/disqus.html

This is the layout file: https://gitlab.com/marcia/blog-test/blob/master/_layouts/post.html

This is the snippet we need to include (https://gitlab.com/gitlab-com/www-gitlab-com/issues/1611#note_38446585):

<div id="disqus_thread"></div>
<script>

/**
*  RECOMMENDED CONFIGURATION VARIABLES: EDIT AND UNCOMMENT THE SECTION BELOW TO INSERT DYNAMIC VALUES FROM YOUR PLATFORM OR CMS.
*  LEARN WHY DEFINING THESE VARIABLES IS IMPORTANT: https://disqus.com/admin/universalcode/#configuration-variables*/
/*
var disqus_config = function () {
this.page.url = PAGE_URL;  // Replace PAGE_URL with your page's canonical URL variable
this.page.identifier = PAGE_IDENTIFIER; // Replace PAGE_IDENTIFIER with your page's unique identifier variable
};
*/
(function() { // DON'T EDIT BELOW THIS LINE
var d = document, s = d.createElement('script');
s.src = 'https://gitlab-docs.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>

added Backend Frontend labels

changed milestone to %10.0

mentioned in issue www-gitlab-com#1611 (closed)

@marcia I know :) There was a WIP MR https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/39/diffs, but priorities changed and we left that behind.

If we are to add comments for the docs site, I'd rather use our forum which runs Discourse https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963. It's similar to disqus. I recall Sytse also asked about this in chat.

WIP MR for Discourse https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/113

Hmm, I don't know if we want Discourse @axil, Sid's request was to add Disqus. I think most of the people will have an account in Disqus, not in Discourse. And as far as I know, Discourse was created for forums, not for comments. ;)

Do you want to double check with him?

@marcia https://gitlab.slack.com/archives/C16HYA2P5/p1499365166827269

Right under my nose :P I misread that comment, I was sure it was about Disqus

Thanks for the correction @axil

changed the description

mentioned in merge request !113 (merged)

assigned to @axil

closed via merge request !113 (merged)