docs: add seo guide #1059
docs: add seo guide #1059
Conversation
Signed-off-by: Christine Belzie <[email protected]>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
EO-friendly URLs Signed-off-by: Christine Belzie <[email protected]>
CBID2
requested review from
quetzalliwrites,
derberg,
asyncapi-bot-eve and
thulieblack
as code owners
Signed-off-by: Christine Belzie <[email protected]>
|
Hey there, @CBID2, thank you for contributing to our OSS project! 🐻 We appreciate your time. Your PR is a good first draft, good work. I will leave you a review today and then simply address the feedback given. |
| @@ -0,0 +1,38 @@ | |||
| --- | |||
There was a problem hiding this comment.
📣 Feedback for Draft 1
What is SEO?
The definition is accurate but could be slightly rephrased. For example, "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 it important in our Documentation?
Could you add a sentence about the potential for increased contributions and community growth through effective SEO?
Headings
- The phrase "chronological order" is confusing because we're not discussing time. It's clearer to say, "hierarchical order".
- Include an example of headings.
Alt Text
- The phrase "avoid writing add every single detail" has a typo. It could be corrected to "avoid writing down every single detail."
- Include an example of good alt text.
URLs
- The guidance is generally good but simplifying the explanation could make it more accessible. For instance, "Use hyphens (-) instead of underscores (_) to separate words in URLs, as search engines treat hyphens as space."
- Add examples of well-structured URLs from our different content buckets such as:
asyncapi.com/docs/concepts/server
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.
Signed-off-by: Christine Belzie <[email protected]>
Signed-off-by: Christine Belzie <[email protected]>
Signed-off-by: Christine Belzie <[email protected]>
…-friendly Co-authored-by: Quetzalli <[email protected]>
Hi @alequetzalli! :) I just finished Draft 2! :) |
docs/styleguide/seo.md
Outdated
| #### 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. |
There was a problem hiding this comment.
What is this? Why did you copy/paste my feedback comment into the documentation? You were supposed to apply the feedback for writing the missing content.
There was a problem hiding this comment.
I was under the impression that this information needed to be added to the guide. My mistake
docs/styleguide/seo.md
Outdated
| - **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: |
There was a problem hiding this comment.
What makes these links SEO friendly? We should also explain how the URL clearly shows our content buckets.
docs/styleguide/seo.md
Outdated
|
|
||
| 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? |
There was a problem hiding this comment.
Hey there, just a reminder that we observe sentence capitalization in headers. Please update and correct all headers accordingly :)
There was a problem hiding this comment.
A reminder that the doc should be written to the audience via "you", not "we." Please go through your doc and update all mentions accordingly.
docs/styleguide/seo.md
Outdated
| 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. |
There was a problem hiding this comment.
| - **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. | |
| - **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. |
This advice contradicts our own documentation outline approach. All our tutorials intentionally have headers such as Introduction, Summary, and Next steps. Please remove this line.
Signed-off-by: Christine <[email protected]>
Signed-off-by: Christine <[email protected]>
Signed-off-by: Christine <[email protected]>
Signed-off-by: Christine <[email protected]>
Signed-off-by: Christine <[email protected]>
…ical documentation
Signed-off-by: Christine <[email protected]>
|
Hi @alequetzalli! :) I made more updates to the SEO guide. |
Signed-off-by: Christine <[email protected]>
|
We need to have a content bucket for the style guides before merging. Once the docs automation from the community repo is done, Quetzalli will give the final go-ahead. Please wait till then 😊 |
|
Still waiting for the automation for the docs to be complete before merging this cc @quetzalliwrites |
Description
This PR adds a guide to help people make their contributions more SEO-friendly.
Related issue(s)
Closes #1256