Please fix documentation site


#1

I am finding working with the Couchbase documentation extremely frustrating (https://developer.couchbase.com/documentation/server/current/introduction/whats-new.html) I hope that by listing out my gripes here, someone from Couchbase can do something about it.

Here are the most frustrating issues:

  1. On Google searches, the links are mostly to 3.x versions of the documentation. You can have someone work with the Google Search Console to get a more up-to-date version in the search results.

  2. Once you are on a particular page, you cannot change Couchbase version without it going back to the “Introduction” page. There is a “New Documentation Available” link but that brings you to the most current version, but I am using the 4.5 version.

  3. The only way I can get the documentation for the page and version I am looking for is to edit the URL itself. However, I usually get a 404 Not Found error instead.

  4. The search using Algolia is useful, but it always brings me to the most current version of Couchbase

Thanks


#2

Hi,
Thanks for your comments - you’ve really got to the heart of the problem of discoverability with the current docs set!
While we’re making efforts to address these issues, it will be some time before all of the work filters through into helping your 4.5 searches. However, I’ll address point-by-point where we’re at with this:

  1. We’ve made some SEO changes designed to reduce the 3.x results. Some improvement is noticeable, but it may be a few weeks before there’s a significant change (eventually end-of-life docs should not show up at all).
  2. The new documentation set - which will make an appearance this summer - should give you direct links between (supported) versions.
  3. This shouldn’t happen too often, but is particularly frustrating when it does! Consideration is being given to the best way of addressing this (i.e. what happens when you jump from a 5.1 doc to version 4.5 when that feature doesn’t exist in the earlier version), such as suggested topics/links. What would you like to see happen?
  4. Algolia is indeed great. I’ve raised the version search problem with the Web team, and it looks like it’s a known issue, although the way the current doc set is structured means the fix is not entirely straightforward.

Thanks again for taking the time to list out your concerns and frustrations. They’re very much on our radar, and although it will take time for all improvements to appear, we hope you’ll be pleased with them when you see them. :slight_smile:


#3

Great to hear your response! For (3), I do not have a concrete suggestion, but if the feature is not available on an older version, the next thing I want to know is from which version is it supported, or links to workarounds / alternatives I can use in the meantime. (or what people used to do before the new feature is added) This may be in the form of a link to a blog post which explains this.

Again, thank you for directly addressing each issue and I look forward to the new improvements in the coming months.


#4

Great suggestions! I’ll be taking them to the next discussion on this.
Fresh input on the problems which don’t have unambiguously good solutions is always welcome :+1: