search

EventStore / documentation

Next-gen documentation website
https://developers.eventstore.com/
10 stars 16 forks source link

Feedback on outdated documentation #669

Open robj-es opened 1 month ago

robj-es commented 1 month ago

@teamchong Submitted this to Rob Johnosn.

Our document site isn’t working well for most users. They usually just Google the information they need, and the top result they find is often from version 5, which is outdated.

I’ve noticed this issue when searching for Event Store information, such as docker eventstore the first result often shows outdated versions like v5 instead of the latest version. I think this might be an SEO issue, and it’s possible that efforts are already underway to address it. However, I wanted to suggest a few additional steps that might help:

  1. Update Sitemap Priorities: https://developers.eventstore.com//sitemap.xml Lower the priority of older version pages (e.g., v5) to 0.5 or below.
  2. Canonical Tags: Ensure all older version pages have canonical tags pointing to the latest version.
  3. Structured Data: Implement structured data on the latest version pages to enhance search engine understanding and improve search appearance.
  4. Google Search Console: Submit the updated sitemap and request re-indexing of the latest version pages. If these steps require too much effort, we could focus on making these changes for the top search result pages only.

@coloradomorrissey and @alexeyzimarev

alexeyzimarev commented 1 month ago

I would instead follow what was started recently and move v5 and TCP client docs to a separate website and make it available as docs.legacy.eventstore.com or something.

alexeyzimarev commented 1 month ago

Adding the sitemap plugin to my PR. Indeed, the current sitemap is utter rubbish. The last modified date is the date of the build. I configured the plugin in my branch to use the file date, which (at least locally) is the actual modification date.

Priority is harder. It needs to be dynamic so we avoid modifying frontmatter (used by the plugin) all the time. I think if we use the semver version like v24.6, remove v and the dot, divide the value by 1000, we should get it right. Priority is a number between 0 and 1. Version 5 will get priority 0.005. Version 24.6 - 0.246.