Docs URLs cleanup & redirects

[quetzalliwrites]

Reason/Context

There are 2 main URL changes this issue will cover:

(1)
The current Docs URLs are going to be updated to match the upcoming Information Architecture (IA) changes coming to our Docs, as mentioned in issue #350.

The new content buckets for our Docs will be the following:

• Concepts
• Tutorials
• How-To Guides
• Tools
• Reference

These new content buckets introduce a different URL structure than what is currently in place. This issue will handle all redirects needed via this method already in place for us here.

(2)
As part of this effort, will improve our Docs overview URL. (i.e. We're changing from current asyncapi.com/docs to docs.asyncapi.com. (Both Fran and Lukasz have mentioned offline they see the value.)

See below a sample list of projects/orgs/etc who have adopted this URL structure:

• https://docs.github.com
• https://docs.aws.amazon.com
• https://docs.netlify.com
• https://docs.sentry.io
• https://docs.confluent.io
• https://docs.microsoft.com
• etc

Change Implications

This issue means that our current URL structures will be planned around the appropriate content buckets.

EXAMPLE 1:
Our current Streetlight tutorial URL is: asyncapi.com/docs/tutorials/streetlights

The NEW URL structure will change this to the following: docs.asyncapi.com/tutorials/streetlights

EXAMPLE 2:
The current Tools section is under: asyncapi.com/docs/community/tooling

The NEW URL structure will have a new section for Tools and all Tools README docs from our diverse repoes will be added to our Docs in this new way: docs.asyncapi.com/tools/modelina.

Let's expand further on this example, still using Modelina as our Tool to document. As we can see in our current Modelina /Docs directory, we have the following subsections...

For the sake of simplicity, let's assume for now that we will copy those docs over to the website repo as they are without editing, which means that we'd have URLs with sub-sections as needed such as the following:

• docs.asyncapi.com/tools/modelina/generators
• docs.asyncapi.com/tools/modelina/integration
• docs.asyncapi.com/tools/modelina/presets
• etc

[boyney123]

Thank you @alequetzalli for explaining it, helped me understand the direction where we are heading 🙇 ⭐

I know we have other feature requests for things like feedback (#453), and working with the docs there might be easier platforms for us to use vs porting over what we have....

I wonder if it's a good time to review the docs solution (code) and maybe make some suggestions for improvement / rewrite them (the code underneath).

For example I have used this (https://docusaurus.io/) in the past, it handles sidebars, navigation, and a whole load of things. We could use this to build docs.asyncapi.com so we don't have to build/maintain so much custom code for our docs.

Here are some other people using it : https://docusaurus.io/showcase

Anyone got thoughts on reviewing our docs codebase if we are moving to docs.asyncapi.com?

cc: @derberg @fmvilas

[quetzalliwrites]

So we don't need to review or change the codebase to make this change… That said if you would like to volunteer to give the code a refresh I guess that would be awesome! :D

@boyney123  I don't think we should be making too many changes though and new content buckets have a higher priority at this point.

[derberg]

I still have some doubts about docs.asyncapi.com. I know many companies do it, but working for one big tech on different projects I know that at least for my old company the only reason was Conway's law. This was always under a different subdomain because it was always a bit different from UI style point of view, mainly because completely different tools were used and (Conway's law reference) a completely different team/department handled documentation. So main website was marketing, bla bla with some CMS and they did not care about Docs team and Docs department had to do their own stuff, with their own people, trying to be consistent but it was always a bit different -> ending up separate subdomain.

This is how it looks for products. Here it is a bit different and let me show alternative examples:

• https://www.gatsbyjs.com/docs/
• https://docusaurus.io/docs
• https://reactjs.org/docs/getting-started.html
• https://nodejs.org/en/docs/

I recall you mentioned something about SEO, so I'm a lot interested in this part. What real benefit is? cause the projects I mentioned above are pretty successful and searchable without subdomain.

---

just to clarify, I'm ok with buckets and reorganization of paths, I'm only against removing asyncapi.com/docs in favor of docs.asyncapi.com

[quetzalliwrites]

I still have some doubts about docs.asyncapi.com. I know many companies do it, but working for one big tech on different projects I know that at least for my old company the only reason was Conway's law.

I can see why the assumption would be that the only reason some Orgs take this route is Conway's Law! On my end, I have worked w/ teams and OSS communities that opted for maintaining a Docs subdomain. It's not just something you come across in Product centric orgs, but I understand why that is certainly the perception.

Let me show you thriving OSS communities that have opted for using a Docs subdomain:

• https://docs.djangoproject.com
• https://docs.ansible.com (RedHat)
• https://docs.flutter.dev/
• https://docs.python.org
• https://docs.docker.com
• https://docs.ros.org/ (robotics FOSS)
• etc

I wanted to make sure I corrected the misinformation/idea that only profit-centric companies are adopting this.

In my own career, I have had OSS folks tell me they "like" having a Docs subdomain because:

1. "We like giving our DevRel/TW maintainers primary ownership over Docs' maintenance."
2. "Our traffic has increased because search engines recognize subdomains as individual websites. Then we set up backlinks to our primary project's domain, which tends to increase its authority."
3. "Leaving the Docs in our main domain didn't make sense to us. We prefer a clear separation of concerns."

just to clarify, I'm ok with buckets and reorganization of paths, I'm only against removing asyncapi.com/docs in favor of docs.asyncapi.com

That said, you bring up a good question: is a new docs subdomain needed as much as our upcoming improved content buckets? I gave it a lot of thought because even though I have been a major proponent of adding a docs subdomain (as you can tell 😂), I wanted to make sure I was 100% sure I had actual reasons for continuing to propose this for our own project.

Personally, I love the way the Django community implemented their docs subdomain because their UI feels smooth. The same upper Navigation is used for both the main domain and the subdomain, and the docs subdomain only has an additional Search bar.

I don't know that I am prepared to further "debate" this topic though 😆, I don't want to push this idea if the community still feels unsure about adding a subdomain for this. I am glad I offered the idea and explained what some OSS communities are doing around this...but if I am the only one who sees value in this specific move, I don't mind following the majority vote. 🙂

I recall you mentioned something about SEO, so I'm a lot interested in this part.
While there are some PROS to subdomains in SEO (as mentioned above), there are also cons. Search engines treat subdomains as separate websites, which means extra maintenance for SEO/dev efforts. (This extra maintenance alone can be considered a good enough con to not go for this.)

Correct usage of 301 redirects address issues of acquiring new SEO rankings. But for every "successful" SEO subdomain case, there are also the horror stories. Sometimes a subdomain can struggle to gain traffic and high rankings in SERPs. Some argue that having a subdomain dilutes your primary domain's ranking power. (As with all SEO questions, it can be hard to know for sure what search bots are going to do, much of the SEO search algos remain a mystery.)

To summarize... SEO-wise ... it can go very good or very bad 🙊😂😀, it's never something you can predict ahead of time. (Want to be honest about the pros/cons of SEO world)

The main reason I find against adding a Docs subdomain is the extra maintenance required, that is certainly something to take seriously.

[derberg]

I do like that in the case of Django it is almost 99% smooth and you might not notice a new subdomain.

As for some examples:

• I still think they do it because of technical limits or conway's law:
  • RedHat that backs Ansible is corpo
  • Docker is not community-led, corpo acquired by another corpo
  • Flutter is Google
  • Django does it this way as docs are handled by another tool (Sfinks) that has advanced templates for translation and probably other things and they keep docs sources with code here in a location separated from main website.

In theory, we could get it done with simple redirecting + making sure that the link to Blog that will be visible on docs.asyncapi.com will take the user to asyncapi.com/blog and not to docs.asyncapi.com/blog.

you made me think after writing this:

Our traffic has increased because search engines recognize subdomains as individual websites. Then we set up backlinks to our primary project's domain, which tends to increase its authority.

If this is really something that may happen, then it is worth trying... I'm just thinking if this is a case in AsyncAPI where we do not have much "competition" as you normally have in a product based company, where docs have to compete with other company content like marketing and that stuff 🤔

@magicmatatjahu @fmvilas what do you think folks?

[fmvilas]

I have no strong opinions on this. Another good thing is that we can get rid of docs from the website repo and move them to their own repo. This will make the website repo smaller and that's a good thing. However, it will increase the logistics as then we'll have two different repos and would probably need to share some UI components.

My gut feeling says: if the benefit is really strong, go ahead. Otherwise, leave it as it is.

[magicmatatjahu]

Like Fran, I don't have a specific opinion, but if we decided to have two projects, we don't need to have two separate repps with some library for UI, because we can always have one project (not monorepo) and render given pages using a flag during the build, so the contributors would focus on the general appearance and then the script would generate given paths for a given version of the page - docs or normal website. It's not easy, but also not impossible.

[quetzalliwrites]

So far, not heard anyone specifically vote for it, which makes me want to leave as is. I am not hearing a collective voice strong enough across the community to merit the move for a docs subdomain.

If this stays this way, I see no reason to continue to campaign a docs subdomain. Unless the community comments more votes for this change, I will simply be moving forward with the idea of leaving it in our primary domain.

I'm just thinking if this is a case in AsyncAPI where we do not have much "competition" as you normally have in a product based company, where docs have to compete with other company content like marketing and that stuff 🤔

Nope, this is not about competition of products/mktg vs docs, we're only talking SEO there. Since search engines count subdomains as another website, this means that now you have 2 sites that Google/FF/Brace/etc will crawl/index/serve vs only 1 (when there's only primary domain). Having 2 sites creates more detailed SERPs, and that will often bring benefits in SEO, traffic, and your CTR (click through rate).

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[quetzalliwrites]

Done via #601 🎉🎉🎉🎉🎉🎉🎉