From 8f176809b6f24fdba5db9b22153d2f8fd77c4db3 Mon Sep 17 00:00:00 2001 From: Christine Belzie Date: Thu, 8 Feb 2024 21:21:59 -0500 Subject: [PATCH 01/35] docs: add seo guide Signed-off-by: Christine Belzie --- docs/styleguide/seo.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/styleguide/seo.md diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md new file mode 100644 index 000000000..492c9fc87 --- /dev/null +++ b/docs/styleguide/seo.md @@ -0,0 +1,33 @@ +# SEO + +## What is SEO? + +SEO (Search Engine Optimization)is the use of methods and strategies to ensure that a website's online content shows up when people search for them. + +### Why is important in our Documentation? + +Implementing SEO practices would make it easier for our users and others to find them. + +### SEO Best Practices + +#### Headings + +Headings are tags used to make sub titles distinctive from each other. When it comes to making them SEO-friendly, it's highly recommended to do the following: + +- **Put them in chronological order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in your tutorial or other piece of documentation. +- **Be descriptive:** Avoid using terms like "Conclusion" and "Introduction" due to their vagueness. Instead, make them specific and ensure they describe the section's content. +- **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, Adding these terms effectively is helpful in reaching the tutorials or other pieces of content you create for our project to a wider audience. + +#### Alt Text + +Alt text are short descriptions of images used to help Google and people who use screen readers gain a better understanding of our tutorials and other pieces of content. To make them SEO-friendly, it's highly recommended to do the following: + +- **Describe the image accurately**: Doing this would help our users understand how to use Asycapi in their work +- **Be concise**: While accuracy is important, avoid writing add every single detail about the image. +- **Use keywords strategically**: Avoid adding every single keyword to your image's alt text. It can overwhelm Google's search engine. + +#### URLs + +URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. To make them more SEO-friendly, use the following methods: + +- From 995f4743cb072f016486ff79210ca0cd26a852cb Mon Sep 17 00:00:00 2001 From: Christine Belzie Date: Thu, 8 Feb 2024 23:01:57 -0500 Subject: [PATCH 02/35] feat: finish section on S EO-friendly URLs Signed-off-by: Christine Belzie --- docs/styleguide/seo.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 492c9fc87..b2d60c3ea 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -30,4 +30,6 @@ Alt text are short descriptions of images used to help Google and people who use URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. To make them more SEO-friendly, use the following methods: -- +- **Make them short:** It'll make the links easier for users to comprehend and find the needed tutorial on our website +- **Use keywords**: Like alt text, effectively adding keywords in the URL would make it easier for Google to find them. +- **Avoid using special characters and spaces:** Characters like hyphens, numbers, ampersands(&), and spaces can make it difficult for the URL to quickly locate the content you're looking for on our site. From a59d5e228865a18f8fd3e899f97c914a111e7b11 Mon Sep 17 00:00:00 2001 From: Christine Belzie Date: Thu, 8 Feb 2024 23:29:51 -0500 Subject: [PATCH 03/35] feat: add frontmatter Signed-off-by: Christine Belzie --- docs/styleguide/seo.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index b2d60c3ea..66d59901b 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -1,3 +1,8 @@ +--- +title: SEO +description: This guide gives advice on how to implement SEO when creating tutorials for our project. +--- + # SEO ## What is SEO? From 30b0dbdaedb7f7681256900031e02f5626da28a9 Mon Sep 17 00:00:00 2001 From: Christine Belzie Date: Fri, 9 Feb 2024 12:10:00 -0500 Subject: [PATCH 04/35] fix: omit heading 1 --- docs/styleguide/seo.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 66d59901b..31508e876 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -3,8 +3,6 @@ title: SEO description: This guide gives advice on how to implement SEO when creating tutorials for our project. --- -# SEO - ## What is SEO? SEO (Search Engine Optimization)is the use of methods and strategies to ensure that a website's online content shows up when people search for them. From 5b9d28280e0077fe5361df8899db9555abc2037f Mon Sep 17 00:00:00 2001 From: Christine Belzie Date: Fri, 16 Feb 2024 16:55:27 -0500 Subject: [PATCH 05/35] feat: made improvements in the sections about SEO and headings Signed-off-by: Christine Belzie --- docs/styleguide/seo.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 31508e876..eb6d70981 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -5,11 +5,11 @@ description: This guide gives advice on how to implement SEO when creating tutor ## What is SEO? -SEO (Search Engine Optimization)is the use of methods and strategies to ensure that a website's online content shows up when people search for them. +SEO (Search Engine Optimization) refers to the methods and strategies used to enhance the visibility of a website's content in search engine results. ### Why is important in our Documentation? -Implementing SEO practices would make it easier for our users and others to find them. +Implementing SEO practices would make it easier for our users and others to find them, resulting in more contributions and people to our community. ### SEO Best Practices @@ -17,10 +17,19 @@ Implementing SEO practices would make it easier for our users and others to find Headings are tags used to make sub titles distinctive from each other. When it comes to making them SEO-friendly, it's highly recommended to do the following: -- **Put them in chronological order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in your tutorial or other piece of documentation. +- **Put them in hierarchcial order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in your tutorial or other piece of documentation. - **Be descriptive:** Avoid using terms like "Conclusion" and "Introduction" due to their vagueness. Instead, make them specific and ensure they describe the section's content. - **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, Adding these terms effectively is helpful in reaching the tutorials or other pieces of content you create for our project to a wider audience. +Here's an example of SEO-friendly headings: + +```md +# Server +## What is Server? +## What is the purpose of servers? +### Cilent and Server +``` + #### Alt Text Alt text are short descriptions of images used to help Google and people who use screen readers gain a better understanding of our tutorials and other pieces of content. To make them SEO-friendly, it's highly recommended to do the following: From 873c3d7c2b46edcd4a7c078901b245a42da89725 Mon Sep 17 00:00:00 2001 From: Christine Belzie Date: Fri, 16 Feb 2024 17:17:04 -0500 Subject: [PATCH 06/35] feat: revise sections about URL and alt text Signed-off-by: Christine Belzie --- docs/styleguide/seo.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index eb6d70981..52e77571d 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -34,14 +34,22 @@ Here's an example of SEO-friendly headings: Alt text are short descriptions of images used to help Google and people who use screen readers gain a better understanding of our tutorials and other pieces of content. To make them SEO-friendly, it's highly recommended to do the following: -- **Describe the image accurately**: Doing this would help our users understand how to use Asycapi in their work -- **Be concise**: While accuracy is important, avoid writing add every single detail about the image. +- **Describe the image accurately**: Doing this would help our users understand how to use Asycapi in their work. +- **Be concise**: While accuracy is important, avoid writing every single detail about the image. - **Use keywords strategically**: Avoid adding every single keyword to your image's alt text. It can overwhelm Google's search engine. +Here's an example of effective alternative text: + +```html +alt="Diagram of EDAs" +``` + #### URLs URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. To make them more SEO-friendly, use the following methods: - **Make them short:** It'll make the links easier for users to comprehend and find the needed tutorial on our website - **Use keywords**: Like alt text, effectively adding keywords in the URL would make it easier for Google to find them. -- **Avoid using special characters and spaces:** Characters like hyphens, numbers, ampersands(&), and spaces can make it difficult for the URL to quickly locate the content you're looking for on our site. +- **Avoid using special characters and spaces:** Use hyphens (-) instead of underscores (_) to separate words in URLs, as search engines treat hyphens as space. + +Here are some examples of SEO-friendly URLs: From ea636c0dd4a73d7be936acec3faec7c753f8fae1 Mon Sep 17 00:00:00 2001 From: Christine Belzie Date: Fri, 16 Feb 2024 17:27:48 -0500 Subject: [PATCH 07/35] feat: add examples of SEO-friendly URLs Signed-off-by: Christine Belzie --- docs/styleguide/seo.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 52e77571d..578391a4b 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -52,4 +52,7 @@ URLs are addresses to webpages and other forms of online content. In the context - **Use keywords**: Like alt text, effectively adding keywords in the URL would make it easier for Google to find them. - **Avoid using special characters and spaces:** Use hyphens (-) instead of underscores (_) to separate words in URLs, as search engines treat hyphens as space. -Here are some examples of SEO-friendly URLs: +Here are some examples of SEO-friendly URLs from our documentation: +- `https://www.asyncapi.com/docs/concepts/application` +- `https://www.asyncapi.com/docs/concepts/server` +- `https://www.asyncapi.com/docs/concepts/message` From 02c1621c8fa7a7c3e566a17813866105e8ab359c Mon Sep 17 00:00:00 2001 From: Christine Belzie Date: Fri, 16 Feb 2024 17:36:10 -0500 Subject: [PATCH 08/35] feat: add section for other ways to make Asyncapi's documentation SEO-friendly Co-authored-by: Quetzalli --- docs/styleguide/seo.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 578391a4b..9e3156ce6 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -56,3 +56,13 @@ Here are some examples of SEO-friendly URLs from our documentation: - `https://www.asyncapi.com/docs/concepts/application` - `https://www.asyncapi.com/docs/concepts/server` - `https://www.asyncapi.com/docs/concepts/message` + +#### Additional Suggestions +- **Meta Descriptions:** Our current docs and blog posts all use meta descriptions and titles. These summaries appear under the title in search results and can significantly impact click-through rates. +- **Mobile-Friendliness:** Mention the importance of ensuring that documentation is mobile-friendly, as this is a factor in search engine rankings. +- **Internal Linking:** Encourage the use of internal linking to other parts of the documentation or the AsyncAPI website to boost SEO and user navigation. +- **Content Quality:** Emphasize the importance of high-quality, original content. Search engines favor content that provides value to users. + **Anchor Text:** +- Be descriptive and relevant. +- Avoid generic phrases like "click here" or "this page". (Instead, use meaningful phrases that give users and search engines an idea of what to expect on the linked page.) +- Vary your anchor text. While it's important to be descriptive, using the exact same anchor text for every link to a particular page can appear spammy to search engines. Try to vary the phrasing while still being clear about the page content. From 0ab1ee6ddf69d08417008660b2d2a778df451087 Mon Sep 17 00:00:00 2001 From: Christine Date: Thu, 22 Feb 2024 02:22:55 +0000 Subject: [PATCH 09/35] fix: remove addtional suggestions section Signed-off-by: Christine --- docs/styleguide/seo.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 9e3156ce6..427960136 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -57,12 +57,3 @@ Here are some examples of SEO-friendly URLs from our documentation: - `https://www.asyncapi.com/docs/concepts/server` - `https://www.asyncapi.com/docs/concepts/message` -#### Additional Suggestions -- **Meta Descriptions:** Our current docs and blog posts all use meta descriptions and titles. These summaries appear under the title in search results and can significantly impact click-through rates. -- **Mobile-Friendliness:** Mention the importance of ensuring that documentation is mobile-friendly, as this is a factor in search engine rankings. -- **Internal Linking:** Encourage the use of internal linking to other parts of the documentation or the AsyncAPI website to boost SEO and user navigation. -- **Content Quality:** Emphasize the importance of high-quality, original content. Search engines favor content that provides value to users. - **Anchor Text:** -- Be descriptive and relevant. -- Avoid generic phrases like "click here" or "this page". (Instead, use meaningful phrases that give users and search engines an idea of what to expect on the linked page.) -- Vary your anchor text. While it's important to be descriptive, using the exact same anchor text for every link to a particular page can appear spammy to search engines. Try to vary the phrasing while still being clear about the page content. From a290e30b89316665870d1c4eb6b96a97037d144f Mon Sep 17 00:00:00 2001 From: Christine Date: Thu, 22 Feb 2024 02:40:39 +0000 Subject: [PATCH 10/35] fix: omit bullet point Signed-off-by: Christine --- docs/styleguide/seo.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 427960136..90c85a419 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -18,7 +18,6 @@ Implementing SEO practices would make it easier for our users and others to find Headings are tags used to make sub titles distinctive from each other. When it comes to making them SEO-friendly, it's highly recommended to do the following: - **Put them in hierarchcial order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in your tutorial or other piece of documentation. -- **Be descriptive:** Avoid using terms like "Conclusion" and "Introduction" due to their vagueness. Instead, make them specific and ensure they describe the section's content. - **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, Adding these terms effectively is helpful in reaching the tutorials or other pieces of content you create for our project to a wider audience. Here's an example of SEO-friendly headings: From 1043e2d629eec8179de9a748016f248e60703dd0 Mon Sep 17 00:00:00 2001 From: Christine Date: Thu, 22 Feb 2024 03:02:49 +0000 Subject: [PATCH 11/35] fix: revise typos Signed-off-by: Christine --- docs/styleguide/seo.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 90c85a419..85fb5c3ed 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -7,9 +7,9 @@ description: This guide gives advice on how to implement SEO when creating tutor SEO (Search Engine Optimization) refers to the methods and strategies used to enhance the visibility of a website's content in search engine results. -### Why is important in our Documentation? +### Why is important in Technical Documentation? -Implementing SEO practices would make it easier for our users and others to find them, resulting in more contributions and people to our community. +Implementing SEO practices would make it easier for users and others to find them, resulting in more contributions and people to the community. ### SEO Best Practices @@ -18,7 +18,7 @@ Implementing SEO practices would make it easier for our users and others to find Headings are tags used to make sub titles distinctive from each other. When it comes to making them SEO-friendly, it's highly recommended to do the following: - **Put them in hierarchcial order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in your tutorial or other piece of documentation. -- **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, Adding these terms effectively is helpful in reaching the tutorials or other pieces of content you create for our project to a wider audience. +- **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, Adding these terms effectively is helpful in ensuring that the tutorials and other pieces of content created reach a wider audience. Here's an example of SEO-friendly headings: @@ -45,7 +45,7 @@ alt="Diagram of EDAs" #### URLs -URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. To make them more SEO-friendly, use the following methods: +URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. To make them SEO-friendly, use the following methods: - **Make them short:** It'll make the links easier for users to comprehend and find the needed tutorial on our website - **Use keywords**: Like alt text, effectively adding keywords in the URL would make it easier for Google to find them. From c5c2cb398c284ade21882577d5d6122f4fa235bf Mon Sep 17 00:00:00 2001 From: Christine Date: Thu, 22 Feb 2024 03:22:35 +0000 Subject: [PATCH 12/35] feat: created section for Anchor text Signed-off-by: Christine --- docs/styleguide/seo.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 85fb5c3ed..3fc693193 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -33,7 +33,7 @@ Here's an example of SEO-friendly headings: Alt text are short descriptions of images used to help Google and people who use screen readers gain a better understanding of our tutorials and other pieces of content. To make them SEO-friendly, it's highly recommended to do the following: -- **Describe the image accurately**: Doing this would help our users understand how to use Asycapi in their work. +- **Describe the image accurately**: Doing this would help our users understand how to use Asyncapi in their work. - **Be concise**: While accuracy is important, avoid writing every single detail about the image. - **Use keywords strategically**: Avoid adding every single keyword to your image's alt text. It can overwhelm Google's search engine. @@ -56,3 +56,7 @@ Here are some examples of SEO-friendly URLs from our documentation: - `https://www.asyncapi.com/docs/concepts/server` - `https://www.asyncapi.com/docs/concepts/message` +#### Anchor Text + +While URLs help users lead people to Asyncapi's content, their anchor texts are the phrases that introduces users to them. Here are some tips to make them SEO-friendly: + \ No newline at end of file From e36abe034e08a77bab9ba1f1e22adf6e4661df8f Mon Sep 17 00:00:00 2001 From: Christine Date: Thu, 29 Feb 2024 03:52:59 +0000 Subject: [PATCH 13/35] feat: add explanation on what makes URL examples SEO-friendly Signed-off-by: Christine --- docs/styleguide/seo.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 3fc693193..b63f3cb0d 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -52,10 +52,13 @@ URLs are addresses to webpages and other forms of online content. In the context - **Avoid using special characters and spaces:** Use hyphens (-) instead of underscores (_) to separate words in URLs, as search engines treat hyphens as space. Here are some examples of SEO-friendly URLs from our documentation: + - `https://www.asyncapi.com/docs/concepts/application` - `https://www.asyncapi.com/docs/concepts/server` - `https://www.asyncapi.com/docs/concepts/message` +In addition to being short, these examples clearly mentions the titles for our content buckets, no hyphens nor special characters and spaces. + #### Anchor Text While URLs help users lead people to Asyncapi's content, their anchor texts are the phrases that introduces users to them. Here are some tips to make them SEO-friendly: From dc7e656960736930116cdc0a1898f01aa043fe4d Mon Sep 17 00:00:00 2001 From: Christine Date: Thu, 29 Feb 2024 04:18:03 +0000 Subject: [PATCH 14/35] feat add tips on making SEO-friendly anchor texts and a section for examples Signed-off-by: Christine --- docs/styleguide/seo.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index b63f3cb0d..f8fbbac9f 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -62,4 +62,11 @@ In addition to being short, these examples clearly mentions the titles for our c #### Anchor Text While URLs help users lead people to Asyncapi's content, their anchor texts are the phrases that introduces users to them. Here are some tips to make them SEO-friendly: - \ No newline at end of file + +- **Implement SEO keywords:** Be descriptive yet mindful of the amount of keywords being used to avoid overwhelming the search engine. +- **Consider the audience's needs**: Think about what the user might be looking for in Asyncapi's documentation and make sure the anchor text reflects this. +- **Maintain the text**: Asyncapi is constantly evolving so it's crucial to update the anchor text to suit the documentation's updates. + +Here are some examples of SEO-friendly anchor texts from our documentation: + + From f69a121180ea3b36eb3a6396c4c4a62de1b113a2 Mon Sep 17 00:00:00 2001 From: Christine Date: Sun, 3 Mar 2024 05:36:57 +0000 Subject: [PATCH 15/35] feat: add examples of SEO-friendly anchor texts Signed-off-by: Christine --- docs/styleguide/seo.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index f8fbbac9f..448e5f0a9 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -69,4 +69,8 @@ While URLs help users lead people to Asyncapi's content, their anchor texts are Here are some examples of SEO-friendly anchor texts from our documentation: - +- `[OpenAPI (aka Swagger)](https://github.com/OAI/OpenAPI-Specification)` +- `[`Server Object`](https://www.asyncapi.com/docs/reference/specification/latest#serverobject)` +- `["the many meanings of Event-Driven Architecture"](https://www.youtube.com/watch?v=STKCRSUsyP0)` + + \ No newline at end of file From 91a9ba283d2be6c3553c47e872477c6693864230 Mon Sep 17 00:00:00 2001 From: Christine Date: Sun, 3 Mar 2024 05:43:14 +0000 Subject: [PATCH 16/35] fix: revise meta description Signed-off-by: Christine --- docs/styleguide/seo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 448e5f0a9..1d2a14471 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -1,6 +1,6 @@ --- title: SEO -description: This guide gives advice on how to implement SEO when creating tutorials for our project. +description: This guide gives advice on how to implement SEO when creating tutorials and other forms of content for Asyncapi. --- ## What is SEO? From 4d6a15f7840fedea5b583cf9e8d2a299163dbdca Mon Sep 17 00:00:00 2001 From: Christine Date: Sun, 3 Mar 2024 05:52:54 +0000 Subject: [PATCH 17/35] feat: add explanation about what makes the example anchor text SEO-friendly Signed-off-by: Christine --- docs/styleguide/seo.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 1d2a14471..44fc97603 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -67,10 +67,10 @@ While URLs help users lead people to Asyncapi's content, their anchor texts are - **Consider the audience's needs**: Think about what the user might be looking for in Asyncapi's documentation and make sure the anchor text reflects this. - **Maintain the text**: Asyncapi is constantly evolving so it's crucial to update the anchor text to suit the documentation's updates. -Here are some examples of SEO-friendly anchor texts from our documentation: +Here are some examples of SEO-friendly anchor texts from Asyncapi's documentation: - `[OpenAPI (aka Swagger)](https://github.com/OAI/OpenAPI-Specification)` - `[`Server Object`](https://www.asyncapi.com/docs/reference/specification/latest#serverobject)` - `["the many meanings of Event-Driven Architecture"](https://www.youtube.com/watch?v=STKCRSUsyP0)` - \ No newline at end of file +These links include relevant keywords such as "OpenAPI(aka Swagger)", "Server Object", and "the many meanings of Event-Driven Architecture", which accurately describes the content they are linked to. From ccbd86366020fd9a5dd5dbe0a9b7387ec4d4128f Mon Sep 17 00:00:00 2001 From: Christine Date: Sun, 3 Mar 2024 06:01:04 +0000 Subject: [PATCH 18/35] fix: revise Markdown errors Signed-off-by: Christine --- docs/styleguide/seo.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 44fc97603..ea7d320c2 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -17,7 +17,7 @@ Implementing SEO practices would make it easier for users and others to find the Headings are tags used to make sub titles distinctive from each other. When it comes to making them SEO-friendly, it's highly recommended to do the following: -- **Put them in hierarchcial order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in your tutorial or other piece of documentation. +- **Put them in hierarchcial order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in yAsyncapi's tutorial or other piece of documentation. - **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, Adding these terms effectively is helpful in ensuring that the tutorials and other pieces of content created reach a wider audience. Here's an example of SEO-friendly headings: @@ -31,11 +31,11 @@ Here's an example of SEO-friendly headings: #### Alt Text -Alt text are short descriptions of images used to help Google and people who use screen readers gain a better understanding of our tutorials and other pieces of content. To make them SEO-friendly, it's highly recommended to do the following: +Alt text are short descriptions of images used to help Google and people who use screen readers gain a better understanding of Asyncapi's tutorials and other pieces of content. To make them SEO-friendly, it's highly recommended to do the following: -- **Describe the image accurately**: Doing this would help our users understand how to use Asyncapi in their work. +- **Describe the image accurately**: Doing this would help Asyncapi's users understand how to use Asyncapi in their work. - **Be concise**: While accuracy is important, avoid writing every single detail about the image. -- **Use keywords strategically**: Avoid adding every single keyword to your image's alt text. It can overwhelm Google's search engine. +- **Use keywords strategically**: Avoid adding every single keyword to the image's alt text. It can overwhelm Google's search engine. Here's an example of effective alternative text: @@ -47,17 +47,17 @@ alt="Diagram of EDAs" URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. To make them SEO-friendly, use the following methods: -- **Make them short:** It'll make the links easier for users to comprehend and find the needed tutorial on our website +- **Make them short:** It'll make the links easier for users to comprehend and find the needed tutorial on Asyncapi's website. - **Use keywords**: Like alt text, effectively adding keywords in the URL would make it easier for Google to find them. - **Avoid using special characters and spaces:** Use hyphens (-) instead of underscores (_) to separate words in URLs, as search engines treat hyphens as space. -Here are some examples of SEO-friendly URLs from our documentation: +Here are some examples of SEO-friendly URLs from Asyncapi's documentation: - `https://www.asyncapi.com/docs/concepts/application` - `https://www.asyncapi.com/docs/concepts/server` - `https://www.asyncapi.com/docs/concepts/message` -In addition to being short, these examples clearly mentions the titles for our content buckets, no hyphens nor special characters and spaces. +In addition to being short, these examples clearly mentions the titles for Asyncapi's content buckets, no hyphens nor special characters and spaces. #### Anchor Text @@ -73,4 +73,4 @@ Here are some examples of SEO-friendly anchor texts from Asyncapi's documentatio - `[`Server Object`](https://www.asyncapi.com/docs/reference/specification/latest#serverobject)` - `["the many meanings of Event-Driven Architecture"](https://www.youtube.com/watch?v=STKCRSUsyP0)` -These links include relevant keywords such as "OpenAPI(aka Swagger)", "Server Object", and "the many meanings of Event-Driven Architecture", which accurately describes the content they are linked to. +These links include relevant keywords such as "OpenAPI(aka Swagger)", "Server Object", and "the many meanings of Event-Driven Architecture", which accurately describes the content they are linked to. From a3d1deb3c86187f280863a67ddda4377c129b9f7 Mon Sep 17 00:00:00 2001 From: Christine Belzie <105683440+CBID2@users.noreply.github.com> Date: Tue, 12 Mar 2024 20:55:24 -0400 Subject: [PATCH 19/35] feat: add some comments --- docs/styleguide/seo.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index ea7d320c2..e26bde904 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -74,3 +74,4 @@ Here are some examples of SEO-friendly anchor texts from Asyncapi's documentatio - `["the many meanings of Event-Driven Architecture"](https://www.youtube.com/watch?v=STKCRSUsyP0)` These links include relevant keywords such as "OpenAPI(aka Swagger)", "Server Object", and "the many meanings of Event-Driven Architecture", which accurately describes the content they are linked to. + From 1dc4c4188f388c66c940a7f503ba1f2c299c4fd2 Mon Sep 17 00:00:00 2001 From: Christine Date: Sun, 31 Mar 2024 05:05:53 +0000 Subject: [PATCH 20/35] feat: finished adding more detail about headings and start another section Signed-off-by: Christine --- docs/styleguide/seo.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index e26bde904..e14801551 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -18,7 +18,8 @@ Implementing SEO practices would make it easier for users and others to find the Headings are tags used to make sub titles distinctive from each other. When it comes to making them SEO-friendly, it's highly recommended to do the following: - **Put them in hierarchcial order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in yAsyncapi's tutorial or other piece of documentation. -- **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, Adding these terms effectively is helpful in ensuring that the tutorials and other pieces of content created reach a wider audience. +- **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, adding these terms effectively is helpful in ensuring that the tutorials and other pieces of content created reach a wider audience. Moz highly recommennds ["implementing keywords in the `h1` and`h2` elements because it is where most users start reading"(Stark Visibility, p.16)](https://starkvisibility.com/wp-content/uploads/2022/04/SEO-Copywriting-101-eBook.pdf) +- **Use them effectively:** While it is important to use headings in hierachcial order, consider using methods like ["putting one `h2` element in the content sections for easier navigation and readability purposes"(Stark Visibility, p.29)](https://starkvisibility.com/wp-content/uploads/2022/04/SEO-Copywriting-101-eBook.pdf) Here's an example of SEO-friendly headings: @@ -28,6 +29,7 @@ Here's an example of SEO-friendly headings: ## What is the purpose of servers? ### Cilent and Server ``` +In addition to using keywords, these headings appear in hierarchial order and appear in their respective content once. #### Alt Text @@ -42,7 +44,7 @@ Here's an example of effective alternative text: ```html alt="Diagram of EDAs" ``` - +The above example is not only concise, but also uses keywords (EDAs) and accurately describes the image used in the tutorial. #### URLs URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. To make them SEO-friendly, use the following methods: @@ -74,4 +76,6 @@ Here are some examples of SEO-friendly anchor texts from Asyncapi's documentatio - `["the many meanings of Event-Driven Architecture"](https://www.youtube.com/watch?v=STKCRSUsyP0)` These links include relevant keywords such as "OpenAPI(aka Swagger)", "Server Object", and "the many meanings of Event-Driven Architecture", which accurately describes the content they are linked to. - + +## Creating High-quality Content + From ae9d05dfb366e5cd59cc7a63de26a0faec8455c3 Mon Sep 17 00:00:00 2001 From: Christine Date: Sun, 31 Mar 2024 05:39:23 +0000 Subject: [PATCH 21/35] feat: added new sections Signed-off-by: Christine --- docs/styleguide/seo.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index e14801551..43d74955c 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -77,5 +77,11 @@ Here are some examples of SEO-friendly anchor texts from Asyncapi's documentatio These links include relevant keywords such as "OpenAPI(aka Swagger)", "Server Object", and "the many meanings of Event-Driven Architecture", which accurately describes the content they are linked to. -## Creating High-quality Content +## Meta Description + +### Internal Linking + + +#### Mobile-Friendly + \ No newline at end of file From 27225f76fa73e783e47224f2f7e61fc85d2270c4 Mon Sep 17 00:00:00 2001 From: Christine Date: Sun, 31 Mar 2024 23:07:01 +0000 Subject: [PATCH 22/35] fix: omit comment and revise markdown formatting Signed-off-by: Christine --- docs/styleguide/seo.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 43d74955c..256192271 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -29,6 +29,7 @@ Here's an example of SEO-friendly headings: ## What is the purpose of servers? ### Cilent and Server ``` + In addition to using keywords, these headings appear in hierarchial order and appear in their respective content once. #### Alt Text @@ -44,6 +45,7 @@ Here's an example of effective alternative text: ```html alt="Diagram of EDAs" ``` + The above example is not only concise, but also uses keywords (EDAs) and accurately describes the image used in the tutorial. #### URLs @@ -78,7 +80,7 @@ Here are some examples of SEO-friendly anchor texts from Asyncapi's documentatio These links include relevant keywords such as "OpenAPI(aka Swagger)", "Server Object", and "the many meanings of Event-Driven Architecture", which accurately describes the content they are linked to. ## Meta Description - + ### Internal Linking From 100f76fc791e9d488ab64e927a07b1d992d32a14 Mon Sep 17 00:00:00 2001 From: Christine Date: Mon, 1 Apr 2024 00:04:35 +0000 Subject: [PATCH 23/35] fix: revise headings Signed-off-by: Christine --- docs/styleguide/seo.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 256192271..92b3046c2 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -30,7 +30,7 @@ Here's an example of SEO-friendly headings: ### Cilent and Server ``` -In addition to using keywords, these headings appear in hierarchial order and appear in their respective content once. +In addition to using keywords, these headings appear in hierarchial order and appear in their respective content once. #### Alt Text @@ -46,7 +46,8 @@ Here's an example of effective alternative text: alt="Diagram of EDAs" ``` -The above example is not only concise, but also uses keywords (EDAs) and accurately describes the image used in the tutorial. +The above example is not only concise, but also uses keywords (EDAs) and accurately describes the image used in the tutorial. + #### URLs URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. To make them SEO-friendly, use the following methods: @@ -73,17 +74,18 @@ While URLs help users lead people to Asyncapi's content, their anchor texts are Here are some examples of SEO-friendly anchor texts from Asyncapi's documentation: -- `[OpenAPI (aka Swagger)](https://github.com/OAI/OpenAPI-Specification)` -- `[`Server Object`](https://www.asyncapi.com/docs/reference/specification/latest#serverobject)` -- `["the many meanings of Event-Driven Architecture"](https://www.youtube.com/watch?v=STKCRSUsyP0)` +- [OpenAPI (aka Swagger)](https://github.com/OAI/OpenAPI-Specification) +- [Server Object](https://www.asyncapi.com/docs/reference/specification/latest#serverobject) +- ["The many meanings of Event-Driven Architecture"](https://www.youtube.com/watch?v=STKCRSUsyP0) These links include relevant keywords such as "OpenAPI(aka Swagger)", "Server Object", and "the many meanings of Event-Driven Architecture", which accurately describes the content they are linked to. -## Meta Description - +## Meta Description -### Internal Linking +Meta descriptions are ["snippets of HTML code that are placed in a web page's header."](https://www.techtarget.com/whatis/definition/meta-description-tag). To make them SEO-friendly, consider following these methods: + +### Internal Linking -#### Mobile-Friendly +### Mobile-Friendly \ No newline at end of file From 6385f0037476dd1e790b86e0b580bfbb0dc00508 Mon Sep 17 00:00:00 2001 From: Christine Date: Mon, 1 Apr 2024 02:45:41 +0000 Subject: [PATCH 24/35] feat: finished section on meta descriptions --- docs/styleguide/seo.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 92b3046c2..0994bd967 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -82,8 +82,23 @@ These links include relevant keywords such as "OpenAPI(aka Swagger)", "Server Ob ## Meta Description -Meta descriptions are ["snippets of HTML code that are placed in a web page's header."](https://www.techtarget.com/whatis/definition/meta-description-tag). To make them SEO-friendly, consider following these methods: - +Meta descriptions are ["snippets of HTML code that are placed in a web page's header."](https://www.techtarget.com/whatis/definition/meta-description-tag). They appear under the title in the search results on Google and can significantly impact click-through rates. To make them SEO-friendly, consider following these methods: + +- **Make them unique:** Meta descriptions that are identical to each other would make it difficult for the content to appear in the search results. +- **Be descriptive** Since this information does not appear in webpages, add enough detail to the content's meta descriptions. It is highly recommended "to keep these descriptions within a range of ["150-300 characters"](https://docs.readthedocs.io/en/stable/guides/technical-docs-seo-guide.html). +- **Be accurate**: Ensure that the meta description includes information that correlates to the blog post or tutorial's topic. Doing so helps its meta description appear in the search engine's results. + +Here are some examples of high-quality meta descriptions from Asyncapi's website: + +- `title: Kafka bindings +description: Learn how to configure Kafka bindings in your AsyncAPI document.` +- `title: "Validate AsyncAPI documents" +description: In this guide, you'll learn multiple ways to validate AsyncAPI documents.` +- `title: Generate code +description: In this tutorial, you'll learn how to generate code from your AsyncAPI document.` + +In addition to having information that correlate to the content's topic, these meta descriptions are concise and contain keywords. + ### Internal Linking From 00944f19b82a184958ab81ee2842a4c4f7ce4138 Mon Sep 17 00:00:00 2001 From: Christine Date: Mon, 1 Apr 2024 04:39:33 +0000 Subject: [PATCH 25/35] feat: revise structure Signed-off-by: Christine --- docs/styleguide/seo.md | 85 ++++++++++++++++++++++++------------------ 1 file changed, 49 insertions(+), 36 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 0994bd967..1340848e4 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -7,50 +7,35 @@ description: This guide gives advice on how to implement SEO when creating tutor SEO (Search Engine Optimization) refers to the methods and strategies used to enhance the visibility of a website's content in search engine results. -### Why is important in Technical Documentation? +## Why is SEO important in technical documentation? Implementing SEO practices would make it easier for users and others to find them, resulting in more contributions and people to the community. -### SEO Best Practices +## SEO best practices -#### Headings +### What are headings? -Headings are tags used to make sub titles distinctive from each other. When it comes to making them SEO-friendly, it's highly recommended to do the following: +Headings are tags used to make sub titles distinctive from each other. + +#### Strategies for making SEO-friendly headings - **Put them in hierarchcial order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in yAsyncapi's tutorial or other piece of documentation. - **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, adding these terms effectively is helpful in ensuring that the tutorials and other pieces of content created reach a wider audience. Moz highly recommennds ["implementing keywords in the `h1` and`h2` elements because it is where most users start reading"(Stark Visibility, p.16)](https://starkvisibility.com/wp-content/uploads/2022/04/SEO-Copywriting-101-eBook.pdf) -- **Use them effectively:** While it is important to use headings in hierachcial order, consider using methods like ["putting one `h2` element in the content sections for easier navigation and readability purposes"(Stark Visibility, p.29)](https://starkvisibility.com/wp-content/uploads/2022/04/SEO-Copywriting-101-eBook.pdf) -Here's an example of SEO-friendly headings: +### Examples of SEO-friendly headings from Asyncapi's documentation ```md -# Server +# Server ## What is Server? ## What is the purpose of servers? -### Cilent and Server -``` - -In addition to using keywords, these headings appear in hierarchial order and appear in their respective content once. - -#### Alt Text - -Alt text are short descriptions of images used to help Google and people who use screen readers gain a better understanding of Asyncapi's tutorials and other pieces of content. To make them SEO-friendly, it's highly recommended to do the following: - -- **Describe the image accurately**: Doing this would help Asyncapi's users understand how to use Asyncapi in their work. -- **Be concise**: While accuracy is important, avoid writing every single detail about the image. -- **Use keywords strategically**: Avoid adding every single keyword to the image's alt text. It can overwhelm Google's search engine. - -Here's an example of effective alternative text: - -```html -alt="Diagram of EDAs" +### Client and Server ``` -The above example is not only concise, but also uses keywords (EDAs) and accurately describes the image used in the tutorial. +### What are URLS? -#### URLs +URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. -URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. To make them SEO-friendly, use the following methods: +#### Strategies for making SEO-friendly URLs - **Make them short:** It'll make the links easier for users to comprehend and find the needed tutorial on Asyncapi's website. - **Use keywords**: Like alt text, effectively adding keywords in the URL would make it easier for Google to find them. @@ -64,15 +49,17 @@ Here are some examples of SEO-friendly URLs from Asyncapi's documentation: In addition to being short, these examples clearly mentions the titles for Asyncapi's content buckets, no hyphens nor special characters and spaces. -#### Anchor Text +### What is Anchor Text? -While URLs help users lead people to Asyncapi's content, their anchor texts are the phrases that introduces users to them. Here are some tips to make them SEO-friendly: + Anchor texts are the phrases that describe a webpage's URL. They give users an idea what to expect before actually reading the content. + +#### Strategies for making SEO-friendly anchor texts - **Implement SEO keywords:** Be descriptive yet mindful of the amount of keywords being used to avoid overwhelming the search engine. - **Consider the audience's needs**: Think about what the user might be looking for in Asyncapi's documentation and make sure the anchor text reflects this. - **Maintain the text**: Asyncapi is constantly evolving so it's crucial to update the anchor text to suit the documentation's updates. -Here are some examples of SEO-friendly anchor texts from Asyncapi's documentation: +### Examples of SEO-friendly anchor texts from Asyncapi's documentation - [OpenAPI (aka Swagger)](https://github.com/OAI/OpenAPI-Specification) - [Server Object](https://www.asyncapi.com/docs/reference/specification/latest#serverobject) @@ -80,15 +67,29 @@ Here are some examples of SEO-friendly anchor texts from Asyncapi's documentatio These links include relevant keywords such as "OpenAPI(aka Swagger)", "Server Object", and "the many meanings of Event-Driven Architecture", which accurately describes the content they are linked to. -## Meta Description +### What is Internal Linking? + +Internal linking is the process of enclosing links to certain sections of a blog post or tutorial in brackets and placing them next to the headings and title. This makes it easier for users to navigate through Asyncapi's content. -Meta descriptions are ["snippets of HTML code that are placed in a web page's header."](https://www.techtarget.com/whatis/definition/meta-description-tag). They appear under the title in the search results on Google and can significantly impact click-through rates. To make them SEO-friendly, consider following these methods: +#### Strategies for making SEO-friendly internal links + +- **Develop a internal link structure**: Consider deciding the types of internal links to use when writing a blog post or documentation for Asyncapi. Doing so would help increase the chances of the content appear in the search results. To learn more about the different styles of internal links, check out the [Types of Internal Links section in "Internal Links for SEO: An Actionable Guide"](https://ahrefs.com/blog/internal-links-for-seo/#types-of-internal-links). +- **Create unique anchor texts:** It's best to avoid using the same anchor text when linking pages so that users won't be confused as they read the content on Asyncapi's website. +- **Include keywords in your anchor text**: This will ensure that the search engine can view the webpage's content. + +### Examples of SEO-friendly anchor texts from Asyncapi's website + +### What are meta descriptions? + +Meta descriptions are ["snippets of HTML code that are placed in a web page's header."](https://www.techtarget.com/whatis/definition/meta-description-tag). They appear under the title in the search results on Google and can significantly impact click-through rates. + +#### Strategies for making SEO-friendly meta descriptions - **Make them unique:** Meta descriptions that are identical to each other would make it difficult for the content to appear in the search results. - **Be descriptive** Since this information does not appear in webpages, add enough detail to the content's meta descriptions. It is highly recommended "to keep these descriptions within a range of ["150-300 characters"](https://docs.readthedocs.io/en/stable/guides/technical-docs-seo-guide.html). - **Be accurate**: Ensure that the meta description includes information that correlates to the blog post or tutorial's topic. Doing so helps its meta description appear in the search engine's results. -Here are some examples of high-quality meta descriptions from Asyncapi's website: +### Examples of SEO-friendly meta descriptions from Asyncapi's website - `title: Kafka bindings description: Learn how to configure Kafka bindings in your AsyncAPI document.` @@ -99,8 +100,20 @@ description: In this tutorial, you'll learn how to generate code from your Async In addition to having information that correlate to the content's topic, these meta descriptions are concise and contain keywords. -### Internal Linking +### Why mobile-friendliness important to technical documentation when making it SEO-friendly? + + +#### Strategies for making mobile and SEO-friendly content + + +### Examples of SEO and mobile-friendly content from Asyncapi's website + + +### Why is quality important when making technical documentation that is SEO-friendly? + + +#### Strategies for making high-quality and SEO-friendly content -### Mobile-Friendly - \ No newline at end of file +### Examples of high-quality and SEO-friendly content from Asyncapi's website + \ No newline at end of file From 129986fa142885921f6cb6310c44aa7e6bca9edb Mon Sep 17 00:00:00 2001 From: Christine Date: Mon, 1 Apr 2024 04:49:32 +0000 Subject: [PATCH 26/35] fix: remove period --- docs/styleguide/seo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 1340848e4..1545717b4 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -81,7 +81,7 @@ Internal linking is the process of enclosing links to certain sections of a blog ### What are meta descriptions? -Meta descriptions are ["snippets of HTML code that are placed in a web page's header."](https://www.techtarget.com/whatis/definition/meta-description-tag). They appear under the title in the search results on Google and can significantly impact click-through rates. +Meta descriptions are ["snippets of HTML code that are placed in a web page's header"](https://www.techtarget.com/whatis/definition/meta-description-tag). They appear under the title in the search results on Google and can significantly impact click-through rates. #### Strategies for making SEO-friendly meta descriptions From 0f21cb8b627774132c53c88ec47d341469886dc9 Mon Sep 17 00:00:00 2001 From: Christine Date: Wed, 3 Apr 2024 04:35:07 +0000 Subject: [PATCH 27/35] docs: finished adding information about mobile and SEO-friendly technical documentation --- docs/styleguide/seo.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 1545717b4..c335ccce4 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -79,9 +79,16 @@ Internal linking is the process of enclosing links to certain sections of a blog ### Examples of SEO-friendly anchor texts from Asyncapi's website +- "In this case, in your AsyncAPI file, you describe the `server`, and therefore the [Server Object](https://www.asyncapi.com/docs/reference/specification/latest#serverObject) holds information about the actual server, including its physical location." +- "JSON Schema Draft 07 is 100% compatible with AsyncAPI schemas. You can also use other standards to describe payload schema, such as [Avro](https://github.com/asyncapi/avro-schema-parser#usage)." +- "Furthermore, the [Pub/sub](/docs/tutorials/getting-started/event-driven-architectures#publishersubscriber) is appealing for IoT use cases due to two key features: support for flexible coupling between publishers/subscribers and inherent support for point-to-multipoint transmission." + ### What are meta descriptions? -Meta descriptions are ["snippets of HTML code that are placed in a web page's header"](https://www.techtarget.com/whatis/definition/meta-description-tag). They appear under the title in the search results on Google and can significantly impact click-through rates. +Meta descriptions are typically ["snippets of HTML code that are placed in a web page's header"](https://www.techtarget.com/whatis/definition/meta-description-tag). They appear under the title in the search results on Google and can significantly impact click-through rates. + +>[!NOTE] +> In the case of Asyncapi's documentation, meta descriptions are written in YAML #### Strategies for making SEO-friendly meta descriptions @@ -101,13 +108,24 @@ description: In this tutorial, you'll learn how to generate code from your Async In addition to having information that correlate to the content's topic, these meta descriptions are concise and contain keywords. ### Why mobile-friendliness important to technical documentation when making it SEO-friendly? - + +Whether it's on a tablet, smartphone, or computer, [people consume most online content on these devices](https://blog.google/products/marketingplatform/analytics/mobile-challenge-and-how-measure-it/). Also, making Asyncapi's content mobile-friendly would bring more users to the site as ["users are more likely to return to and have a high opinion of a product if it's website is mobile-friendly"](https://www.webfx.com/blog/web-design/user-experience-matters-marketing/). Lastly, mobile SEO-friendly technical documentation appears more in search results. #### Strategies for making mobile and SEO-friendly content - + +Here are some ways to make blog posts and documentation for Asyncapi's website mobile and SEO-friendly. + +- **Use smaller images and videos**: Large images and videos can cause the documentation on Asyncapi's website to appear at slower rates, which create an unpleasant user-experience. + +- **Use mobile-friendly font**: Some fonts can be hard to read on mobile devices, so it's crucial to picks font styles and sizes that can be adaptable to their screen sizes. It highly recommended to use styles like ["Arial, Tahoma, Verdana for headings and Times New Roman, Georgia, Bookman for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/) and sizes like ["14-16 point font for headings and 12-point for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/). +- **Give each topic its own page and/or section**: Consider putting a link to the next page or implementing internal links. It'll help users the project's docs and blog post have an easier time navigating the site. + +>[!TIP] +> Consider using testing tools like [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) to ensure that the proposed blog post, tutorial, or other form of documentation for Asyncapi is mobile and SEO-friendly if quick results are needed. ### Examples of SEO and mobile-friendly content from Asyncapi's website - + + ### Why is quality important when making technical documentation that is SEO-friendly? From 93580b4c53a20a3b7c84f2e748c3ebf2dd79974f Mon Sep 17 00:00:00 2001 From: Christine Date: Wed, 3 Apr 2024 04:38:34 +0000 Subject: [PATCH 28/35] docs: add Additional resources section --- docs/styleguide/seo.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index c335ccce4..7261cd716 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -134,4 +134,7 @@ Here are some ways to make blog posts and documentation for Asyncapi's website m ### Examples of high-quality and SEO-friendly content from Asyncapi's website - \ No newline at end of file + + +## Additional resources + \ No newline at end of file From 8629680e80a72bedfd9b8fe3898dd11c15443e12 Mon Sep 17 00:00:00 2001 From: Christine Date: Wed, 3 Apr 2024 04:39:08 +0000 Subject: [PATCH 29/35] docs: fix formatting issues --- docs/styleguide/seo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 7261cd716..35506f3ac 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -136,5 +136,5 @@ Here are some ways to make blog posts and documentation for Asyncapi's website m ### Examples of high-quality and SEO-friendly content from Asyncapi's website -## Additional resources +## Additional resources \ No newline at end of file From 518fb48a9e5df31b5246262bebb55ec5cc009e1a Mon Sep 17 00:00:00 2001 From: Christine Date: Thu, 18 Apr 2024 20:59:24 +0000 Subject: [PATCH 30/35] docs: add section on image optimization Signed-off-by: Christine --- docs/styleguide/seo.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 35506f3ac..002bab6ad 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -19,8 +19,8 @@ Headings are tags used to make sub titles distinctive from each other. #### Strategies for making SEO-friendly headings -- **Put them in hierarchcial order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in yAsyncapi's tutorial or other piece of documentation. -- **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, adding these terms effectively is helpful in ensuring that the tutorials and other pieces of content created reach a wider audience. Moz highly recommennds ["implementing keywords in the `h1` and`h2` elements because it is where most users start reading"(Stark Visibility, p.16)](https://starkvisibility.com/wp-content/uploads/2022/04/SEO-Copywriting-101-eBook.pdf) +- **Put them in hierarchical order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in Asyncapi's tutorial or other piece of documentation. +- **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, adding these terms effectively is helpful in ensuring that the tutorials and other pieces of content created reach a wider audience. It is highly recommended to [implement keywords in the `h1` and`h2` elements because it is where most users start reading"(Stark Visibility, p.16)](https://starkvisibility.com/wp-content/uploads/2022/04/SEO-Copywriting-101-eBook.pdf) ### Examples of SEO-friendly headings from Asyncapi's documentation @@ -123,18 +123,26 @@ Here are some ways to make blog posts and documentation for Asyncapi's website m >[!TIP] > Consider using testing tools like [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) to ensure that the proposed blog post, tutorial, or other form of documentation for Asyncapi is mobile and SEO-friendly if quick results are needed. -### Examples of SEO and mobile-friendly content from Asyncapi's website - - - ### Why is quality important when making technical documentation that is SEO-friendly? - + +While implementing the previously mentioned strategies are important, ensuring that the content is original and high-quality are also important when creating SEO-friendly content. Search engines tend to favor content that provides value for online users. #### Strategies for making high-quality and SEO-friendly content - -### Examples of high-quality and SEO-friendly content from Asyncapi's website - +Here are some questions to consider when creating SEO-friendly and original content: + +- Is the content interactive and engaging? +- Is the information I present accurate? +- Is the content too technical for its intended audience? + +### Images + +The way a technical documentation's images are presented influences how it shows up in the search engine rankings, so it's important to optimize them in the best way possible. + +### Strategies for making images SEO-friendly + +Here are ways to make SEO-friendly images: -## Additional resources - \ No newline at end of file +- **Create descriptive alt text**: Ensure that it describes the image's context a purpose. Doing so makes it easier for search engines to understand why it is being used, [especially when the image fails to appear on screen](https://rb.gy/5axft9). +- **Use search-engine supported image formats**: [Google tends to support images that are `JPEG`, `SVG`, and `PNG`](https://developers.google.com/search/docs/appearance/google-images#supported-image-formats) format, so consider saving the images in these formats. +- **Keep their sizes not too large**: [Large image file sizes can make cause the site to load slowly](https://developers.google.com/search/docs/appearance/google-images#good-quality-photos%20optimize-for-speed) so remember to reduce and compress them before add them to the content. From 21c7e1c3eff7bf131ab47bd85ccaafa5cd0bdd07 Mon Sep 17 00:00:00 2001 From: Christine Date: Sun, 26 May 2024 22:36:56 +0000 Subject: [PATCH 31/35] docs: made edits --- docs/styleguide/seo.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 002bab6ad..07bed82e0 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -117,11 +117,11 @@ Here are some ways to make blog posts and documentation for Asyncapi's website m - **Use smaller images and videos**: Large images and videos can cause the documentation on Asyncapi's website to appear at slower rates, which create an unpleasant user-experience. -- **Use mobile-friendly font**: Some fonts can be hard to read on mobile devices, so it's crucial to picks font styles and sizes that can be adaptable to their screen sizes. It highly recommended to use styles like ["Arial, Tahoma, Verdana for headings and Times New Roman, Georgia, Bookman for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/) and sizes like ["14-16 point font for headings and 12-point for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/). +- **Use mobile-friendly fonts**: Some fonts can be hard to read on mobile devices, so it's crucial to picks font styles and sizes that can be adaptable to their screen sizes. It highly recommended to use styles like ["Arial, Tahoma, Verdana for headings and Times New Roman, Georgia, Bookman for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/) and sizes like ["14-16 point font for headings and 12-point for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/). - **Give each topic its own page and/or section**: Consider putting a link to the next page or implementing internal links. It'll help users the project's docs and blog post have an easier time navigating the site. >[!TIP] -> Consider using testing tools like [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) to ensure that the proposed blog post, tutorial, or other form of documentation for Asyncapi is mobile and SEO-friendly if quick results are needed. +> Consider using testing tools like [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) to ensure that the proposed blog post, tutorial, or update to Aynscapi's documentation is mobile and SEO-friendly if quick results are needed. ### Why is quality important when making technical documentation that is SEO-friendly? @@ -129,7 +129,7 @@ While implementing the previously mentioned strategies are important, ensuring t #### Strategies for making high-quality and SEO-friendly content -Here are some questions to consider when creating SEO-friendly and original content: +Consider asking yourself the following questions to ensure the content being submitted to Asyncapi's blog or documentation is high-quality and SEO-friendly: - Is the content interactive and engaging? - Is the information I present accurate? @@ -144,5 +144,5 @@ The way a technical documentation's images are presented influences how it shows Here are ways to make SEO-friendly images: - **Create descriptive alt text**: Ensure that it describes the image's context a purpose. Doing so makes it easier for search engines to understand why it is being used, [especially when the image fails to appear on screen](https://rb.gy/5axft9). -- **Use search-engine supported image formats**: [Google tends to support images that are `JPEG`, `SVG`, and `PNG`](https://developers.google.com/search/docs/appearance/google-images#supported-image-formats) format, so consider saving the images in these formats. -- **Keep their sizes not too large**: [Large image file sizes can make cause the site to load slowly](https://developers.google.com/search/docs/appearance/google-images#good-quality-photos%20optimize-for-speed) so remember to reduce and compress them before add them to the content. +- **Use search-engine supported image formats**: [`JPEG`, `SVG`, and `PNG`](https://developers.google.com/search/docs/appearance/google-images#supported-image-formats) are the common formats that appear in Google's search rankings, so consider saving the images in these formats. +- **Be mindful of the images' file size**: [Large image file sizes can make cause the site to load slowly](https://developers.google.com/search/docs/appearance/google-images#good-quality-photos%20optimize-for-speed) so remember to reduce and compress them before add them to the content. From f551555ed2eec8f1e0e15f42e85b7f4572324e0b Mon Sep 17 00:00:00 2001 From: Christine Date: Sun, 2 Jun 2024 22:16:45 +0000 Subject: [PATCH 32/35] docs: fix explanation --- docs/styleguide/seo.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 07bed82e0..60624a088 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -132,7 +132,7 @@ While implementing the previously mentioned strategies are important, ensuring t Consider asking yourself the following questions to ensure the content being submitted to Asyncapi's blog or documentation is high-quality and SEO-friendly: - Is the content interactive and engaging? -- Is the information I present accurate? +- Is the information presented accurate? - Is the content too technical for its intended audience? ### Images @@ -145,4 +145,4 @@ Here are ways to make SEO-friendly images: - **Create descriptive alt text**: Ensure that it describes the image's context a purpose. Doing so makes it easier for search engines to understand why it is being used, [especially when the image fails to appear on screen](https://rb.gy/5axft9). - **Use search-engine supported image formats**: [`JPEG`, `SVG`, and `PNG`](https://developers.google.com/search/docs/appearance/google-images#supported-image-formats) are the common formats that appear in Google's search rankings, so consider saving the images in these formats. -- **Be mindful of the images' file size**: [Large image file sizes can make cause the site to load slowly](https://developers.google.com/search/docs/appearance/google-images#good-quality-photos%20optimize-for-speed) so remember to reduce and compress them before add them to the content. +- **Be mindful of the images' file size**: [Large image file sizes can make cause the site to load slowly](https://developers.google.com/search/docs/appearance/google-images#good-quality-photos%20optimize-for-speed) so reduce and compress them before adding them to the content. From f3dc2242d04346c94a3e72a7f2c1a8279830b775 Mon Sep 17 00:00:00 2001 From: Christine Date: Wed, 5 Jun 2024 01:38:49 +0000 Subject: [PATCH 33/35] docs: revise description Signed-off-by: Christine --- docs/styleguide/seo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 60624a088..3b11b5f5b 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -137,7 +137,7 @@ Consider asking yourself the following questions to ensure the content being sub ### Images -The way a technical documentation's images are presented influences how it shows up in the search engine rankings, so it's important to optimize them in the best way possible. +The way a technical documentation's images are presented influences how they show up in a search engine's rankings, so it's important to optimize them in the best way possible. ### Strategies for making images SEO-friendly From 7c77e387f38c0ad49202e2a8ea783445847a7790 Mon Sep 17 00:00:00 2001 From: Christine Date: Mon, 1 Jul 2024 03:59:46 +0000 Subject: [PATCH 34/35] docs: change sentence --- docs/styleguide/seo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 3b11b5f5b..0d0ff2b7c 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -20,7 +20,7 @@ Headings are tags used to make sub titles distinctive from each other. #### Strategies for making SEO-friendly headings - **Put them in hierarchical order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in Asyncapi's tutorial or other piece of documentation. -- **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, adding these terms effectively is helpful in ensuring that the tutorials and other pieces of content created reach a wider audience. It is highly recommended to [implement keywords in the `h1` and`h2` elements because it is where most users start reading"(Stark Visibility, p.16)](https://starkvisibility.com/wp-content/uploads/2022/04/SEO-Copywriting-101-eBook.pdf) +- **Use relevant keywords:** Since sites like Google often use keywords to help people's online content appear on the web, adding these terms effectively is helpful in ensuring that the tutorials and other pieces of content created reach a wider audience. It is highly recommended to [implement keywords in the `h1` and`h2` elements because it is where most users start reading"(Stark Visibility, p.16)](https://starkvisibility.com/wp-content/uploads/2022/04/SEO-Copywriting-101-eBook.pdf) ### Examples of SEO-friendly headings from Asyncapi's documentation From 8fde226250008907cd48c912bf7c79623f69a6cc Mon Sep 17 00:00:00 2001 From: Christine Date: Mon, 1 Jul 2024 04:21:50 +0000 Subject: [PATCH 35/35] fix: revise errors Signed-off-by: Christine --- docs/styleguide/seo.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/styleguide/seo.md b/docs/styleguide/seo.md index 0d0ff2b7c..c2f0b8e55 100644 --- a/docs/styleguide/seo.md +++ b/docs/styleguide/seo.md @@ -88,7 +88,7 @@ Internal linking is the process of enclosing links to certain sections of a blog Meta descriptions are typically ["snippets of HTML code that are placed in a web page's header"](https://www.techtarget.com/whatis/definition/meta-description-tag). They appear under the title in the search results on Google and can significantly impact click-through rates. >[!NOTE] -> In the case of Asyncapi's documentation, meta descriptions are written in YAML +> In the case of Asyncapi's documentation, meta descriptions are written in YAML. #### Strategies for making SEO-friendly meta descriptions @@ -117,19 +117,19 @@ Here are some ways to make blog posts and documentation for Asyncapi's website m - **Use smaller images and videos**: Large images and videos can cause the documentation on Asyncapi's website to appear at slower rates, which create an unpleasant user-experience. -- **Use mobile-friendly fonts**: Some fonts can be hard to read on mobile devices, so it's crucial to picks font styles and sizes that can be adaptable to their screen sizes. It highly recommended to use styles like ["Arial, Tahoma, Verdana for headings and Times New Roman, Georgia, Bookman for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/) and sizes like ["14-16 point font for headings and 12-point for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/). +- **Use mobile-friendly fonts**: Some fonts can be hard to read on mobile devices, so it's crucial to picks font styles and sizes that can be adaptable to their screen sizes. It highly recommended to use styles like ["Arial, Tahoma, and Verdana for headings. For text, it is best to use Times New Roman, Georgia, and Bookman"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/). For sizes, it's best to use ["14-16 point font for headings and 12-point for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/). - **Give each topic its own page and/or section**: Consider putting a link to the next page or implementing internal links. It'll help users the project's docs and blog post have an easier time navigating the site. >[!TIP] -> Consider using testing tools like [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) to ensure that the proposed blog post, tutorial, or update to Aynscapi's documentation is mobile and SEO-friendly if quick results are needed. +> Need quicker results? Consider using testing tools like [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) to ensure that the proposed blog post, tutorial, or update to Aynscapi's documentation is mobile and SEO-friendly. ### Why is quality important when making technical documentation that is SEO-friendly? -While implementing the previously mentioned strategies are important, ensuring that the content is original and high-quality are also important when creating SEO-friendly content. Search engines tend to favor content that provides value for online users. +Search engines tend to favor content that provides value for online users. Therefore, it's important to ensure that the content is high-quality. #### Strategies for making high-quality and SEO-friendly content -Consider asking yourself the following questions to ensure the content being submitted to Asyncapi's blog or documentation is high-quality and SEO-friendly: +When writing a post for Asyncapi's blog or contributing to its documentation, consider asking the following questions to ensure it is high-quality and SEO-friendly: - Is the content interactive and engaging? - Is the information presented accurate? @@ -141,8 +141,8 @@ The way a technical documentation's images are presented influences how they sho ### Strategies for making images SEO-friendly -Here are ways to make SEO-friendly images: +To make SEO-friendly images, it is recommended to the following methods: - **Create descriptive alt text**: Ensure that it describes the image's context a purpose. Doing so makes it easier for search engines to understand why it is being used, [especially when the image fails to appear on screen](https://rb.gy/5axft9). - **Use search-engine supported image formats**: [`JPEG`, `SVG`, and `PNG`](https://developers.google.com/search/docs/appearance/google-images#supported-image-formats) are the common formats that appear in Google's search rankings, so consider saving the images in these formats. -- **Be mindful of the images' file size**: [Large image file sizes can make cause the site to load slowly](https://developers.google.com/search/docs/appearance/google-images#good-quality-photos%20optimize-for-speed) so reduce and compress them before adding them to the content. +- **Be mindful of the images' file size**: [Large image file sizes can make cause the site to load slowly](https://developers.google.com/search/docs/appearance/google-images#good-quality-photos-optimize-for-speed) so reduce and compress them before adding them to the documentation or blog post.